| Message ID | 20190103013110.6849-9-laurent.pinchart@ideasonboard.com |
|---|---|
| State | Accepted |
| Headers | show |
| Series |
|
| Related | show |
Hi Laurent, Thanks for your work. On 2019-01-03 03:31:10 +0200, Laurent Pinchart wrote: > Miscellaneous documentation improvements for the PipelineHandler and > related classes. > > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se> > --- > src/libcamera/pipeline_handler.cpp | 125 ++++++++++++++++++++--------- > 1 file changed, 88 insertions(+), 37 deletions(-) > > diff --git a/src/libcamera/pipeline_handler.cpp b/src/libcamera/pipeline_handler.cpp > index a737f222b465..093821d4c471 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 */ > -- > Regards, > > Laurent Pinchart > > _______________________________________________ > libcamera-devel mailing list > libcamera-devel@lists.libcamera.org > https://lists.libcamera.org/listinfo/libcamera-devel
diff --git a/src/libcamera/pipeline_handler.cpp b/src/libcamera/pipeline_handler.cpp index a737f222b465..093821d4c471 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 */
Miscellaneous documentation improvements for the PipelineHandler and related classes. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> --- src/libcamera/pipeline_handler.cpp | 125 ++++++++++++++++++++--------- 1 file changed, 88 insertions(+), 37 deletions(-)