summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLaurent Pinchart <laurent.pinchart@ideasonboard.com>2018-12-31 09:29:47 +0200
committerLaurent Pinchart <laurent.pinchart@ideasonboard.com>2019-01-04 00:23:33 +0200
commit5af15d1931de3f931b37930c5fa254a4ff92a7c5 (patch)
tree847d8cda6f759fa13c2e2eac9a9491fb6bb4d0b2
parent2d73fd9eca8fc7bfb7d513ed5b4c6d31903915bb (diff)
libcamera: pipeline_handler: Improve documentation
Miscellaneous documentation improvements for the PipelineHandler and related classes. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Jacopo Mondi <jacopo@jmondi.org> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
-rw-r--r--src/libcamera/pipeline_handler.cpp125
1 files changed, 88 insertions, 37 deletions
diff --git a/src/libcamera/pipeline_handler.cpp b/src/libcamera/pipeline_handler.cpp
index a737f222..093821d4 100644
--- a/src/libcamera/pipeline_handler.cpp
+++ b/src/libcamera/pipeline_handler.cpp
@@ -11,48 +11,98 @@
/**
* \file pipeline_handler.h
- * \brief Create pipelines and cameras from one or more media devices
+ * \brief Create pipelines and cameras from a set of media devices
*
* Each pipeline supported by libcamera needs to be backed by a pipeline
- * handler implementation which describes the one or many media devices
- * needed for a pipeline to function properly.
+ * handler implementation that operate on a set of media devices. The pipeline
+ * handler is responsible for matching the media devices it requires with the
+ * devices present in the system, and once all those devices can be acquired,
+ * create corresponding Camera instances.
*
- * The pipeline handler is responsible for providing a description of the
- * media devices it requires to operate. Once all media devices can be
- * provided the pipeline handler can acquire them and create camera
- * devices that utilize the acquired media devices.
- *
- * To make it a bit less bit complicated to write pipe line handlers a
- * macro REGISTER_PIPELINE_HANDLER() is provided which allows a pipeline
- * handler implementation to register itself with the library with ease.
+ * Every subclass of PipelineHandler shall be registered with libcamera using
+ * the REGISTER_PIPELINE_HANDLER() macro.
*/
namespace libcamera {
/**
* \class PipelineHandler
- * \brief Find a set of media devices and provide cameras
+ * \brief Create and manage cameras based on a set of media devices
*
- * The responsibility of a PipelineHandler is to describe all media
- * devices it would need in order to provide cameras to the system.
+ * The PipelineHandler matches the media devices provided by a DeviceEnumerator
+ * with the pipelines it supports and creates corresponding Camera devices.
+ */
+
+/**
+ * \fn PipelineHandler::match(DeviceEnumerator *enumerator)
+ * \brief Match media devices and create camera instances
+ *
+ * This function is the main entry point of the pipeline handler. It is called
+ * by the device enumerator with the enumerator passed as an argument. It shall
+ * acquire from the enumerator all the media devices it needs for a single
+ * pipeline and create one or multiple Camera instances.
+ *
+ * If all media devices needed by the pipeline handler are found, they must all
+ * be acquired by a call to MediaDevice::acquire(). This function shall then
+ * create the corresponding Camera instances, store them internally, and return
+ * true. Otherwise it shall not acquire any media device (or shall release all
+ * the media devices is has acquired by calling MediaDevice::release()) and
+ * return false.
+ *
+ * If multiple instances of a pipeline are available in the system, the
+ * PipelineHandler class will be instanciated once per instance, and its match()
+ * function called for every instance. Each call shall acquire media devices for
+ * one pipeline instance, until all compatible media devices are exhausted.
+ *
+ * If this function returns true, a new instance of the pipeline handler will
+ * be created and its match() function called,
+ *
+ * \return true if media devices have been acquired and camera instances
+ * created, or false otherwise
+ */
+
+/**
+ * \fn PipelineHandler::count()
+ * \brief Retrieve the number of cameras handled by this pipeline handler
+ * \return the number of cameras that were created by the match() function
+ */
+
+/**
+ * \fn PipelineHandler::camera(unsigned int id)
+ * \brief Retrieve one of the cameras handled by this pipeline handler
+ * \param[in] id the camera index
+ * \return a pointer to the Camera identified by \a id
*/
/**
* \class PipelineHandlerFactory
- * \brief Keep a registry and create instances of available pipeline handlers
- *
- * The responsibility of the PipelineHandlerFactory is to keep a list
- * of all pipelines in the system. Each pipeline handler should register
- * it self with the factory using the REGISTER_PIPELINE_HANDLER() macro.
+ * \brief Registration of PipelineHandler classes and creation of instances
+ *
+ * To facilitate discovery and instantiation of PipelineHandler classes, the
+ * PipelineHandlerFactory class maintains a registry of pipeline handler
+ * classes. Each PipelineHandler subclass shall register itself using the
+ * REGISTER_PIPELINE_HANDLER() macro, which will create a corresponding
+ * instance of a PipelineHandlerFactory subclass and register it with the
+ * static list of factories.
*/
/**
- * \brief Add a pipeline handler to the global list
+ * \fn PipelineHandlerFactory::create()
+ * \brief Create an instance of the PipelineHandler corresponding to the factory
*
- * \param[in] name Name of the pipeline handler to add
- * \param[in] factory Factory to use to construct the pipeline
+ * This virtual function is implemented by the REGISTER_PIPELINE_HANDLER() macro.
+ *
+ * \return a pointer to a newly constructed instance of the PipelineHandler
+ * subclass corresponding to the factory
+ */
+
+/**
+ * \brief Add a pipeline handler class to the registry
+ * \param[in] name Name of the pipeline handler class
+ * \param[in] factory Factory to use to construct the pipeline handler
*
- * The caller is responsible to guarantee the uniqueness of the pipeline name.
+ * The caller is responsible to guarantee the uniqueness of the pipeline handler
+ * name.
*/
void PipelineHandlerFactory::registerType(const std::string &name,
PipelineHandlerFactory *factory)
@@ -68,15 +118,16 @@ void PipelineHandlerFactory::registerType(const std::string &name,
}
/**
- * \brief Create a new pipeline handler and try to match the media devices it requires
- *
- * \param[in] name Name of the pipeline handler to try
+ * \brief Create an instance of a pipeline handler if it matches media devices
+ * present in the system
+ * \param[in] name Name of the pipeline handler to instantiate
* \param[in] enumerator Device enumerator to search for a match for the handler
*
- * Try to match the media devices pipeline \a name requires against the ones
- * registered in \a enumerator.
+ * This function matches the media devices required by pipeline \a name against
+ * the devices enumerated by \a enumerator.
*
- * \return Pipeline handler if a match was found, nullptr otherwise
+ * \return the newly created pipeline handler instance if a match was found, or
+ * nullptr otherwise
*/
PipelineHandler *PipelineHandlerFactory::create(const std::string &name,
DeviceEnumerator *enumerator)
@@ -100,9 +151,10 @@ PipelineHandler *PipelineHandlerFactory::create(const std::string &name,
}
/**
- * \brief List all names of piepline handlers from the global list
+ * \brief Retrieve the names of all pipeline handlers registered with the
+ * factory
*
- * \return List of registerd pipeline handler names
+ * \return a list of all registered pipeline handler names
*/
std::vector<std::string> PipelineHandlerFactory::handlers()
{
@@ -116,12 +168,12 @@ std::vector<std::string> PipelineHandlerFactory::handlers()
}
/**
- * \brief Static global list of pipeline handlers
+ * \brief Retrieve the list of all pipeline handler factories
*
* The static factories map is defined inside the function to ensures it gets
* initialized on first use, without any dependency on link order.
*
- * \return Global list of pipeline handlers
+ * \return the list of pipeline handler factories
*/
std::map<std::string, PipelineHandlerFactory *> &PipelineHandlerFactory::registry()
{
@@ -131,12 +183,11 @@ std::map<std::string, PipelineHandlerFactory *> &PipelineHandlerFactory::registr
/**
* \def REGISTER_PIPELINE_HANDLER
- * \brief Register a pipeline handler with the global list
- *
+ * \brief Register a pipeline handler with the pipeline handler factory
* \param[in] handler Class name of PipelineHandler derived class to register
*
- * Register a specific pipeline handler with the global list and make it
- * available to try and match devices.
+ * Register a PipelineHandler subclass with the factory and make it available to
+ * try and match devices.
*/
} /* namespace libcamera */