[libcamera-devel,v4,0/3] Developer Guides

9337 mbox series

Hi All,

Here is the culmination of work from Chris, Jacopo and Myself preparing
some developer guides for libcamera. This is marked as v4, as they are
based upon earlier versions of work previously posted by Chris.

These three guides aim to cover detail across the areas that a developer
wanting to make use of libcamera would look at, including a dedicated
walkthrough of the steps of creating a new pipeline handler, or a user
application which will make use of libcamera to capture frames.

The guides start with an introduction and overview, which replicates
quite a bit from the existing "Docs" page, but forms part of refactoring
that documentation.

The Pipeline handler guide walks through the creation of a new pipeline
handler from scratch, implementing a PipelineHandlerVivid for the
virtual video test driver provided by the kernel. The aim of this guide
is to provide readers with a full walkthrough of the various functions
which must be impelmented when writing a new pipeline handler, and can
be followed without having a real device available (however the 'vivid'
module must be provided by your kernel or distribution).

The Application writers guide discusses key aspects as the reader
implements a basic application to use the CameraManager to obtain a
camera, configure it, and capture frames.

An IPA writers guide is expected in the near future, but due to the
current activity and changes ongoing with the IPA API, that will be
provided after the current work activity with IPC has settled.

These guides are not yet built by the libcamera.org website (further
refactoring and organising will happen first), but are integrated into
any local build which can be generated with Sphinx during the normal
libcamera build process.

Further expansion to all of these documents is also likely, but I hope
to integrate these in their current form and build on top.


Chris Chinchilla (3):
  Documentation: Guides: Developers Guide to Libcamera
  Documentation: Guides: Pipeline Handler Writers Guide
  Documentation: Guides: Application Writers Guide

 .../guides/application-developer.rst          |  644 +++++++
 Documentation/guides/introduction.rst         |  319 ++++
 Documentation/guides/pipeline-handler.rst     | 1473 +++++++++++++++++
 Documentation/index.rst                       |    4 +
 Documentation/meson.build                     |    3 +
 5 files changed, 2443 insertions(+)
 create mode 100644 Documentation/guides/application-developer.rst
 create mode 100644 Documentation/guides/introduction.rst
 create mode 100644 Documentation/guides/pipeline-handler.rst

Hi Kieran,

Thank you for these long awaited patches :-)

On Thu, Aug 20, 2020 at 02:47:48PM +0100, Kieran Bingham wrote:
> Hi All,
> 
> Here is the culmination of work from Chris, Jacopo and Myself preparing
> some developer guides for libcamera. This is marked as v4, as they are
> based upon earlier versions of work previously posted by Chris.
> 
> These three guides aim to cover detail across the areas that a developer
> wanting to make use of libcamera would look at, including a dedicated
> walkthrough of the steps of creating a new pipeline handler, or a user
> application which will make use of libcamera to capture frames.
> 
> The guides start with an introduction and overview, which replicates
> quite a bit from the existing "Docs" page, but forms part of refactoring
> that documentation.
> 
> The Pipeline handler guide walks through the creation of a new pipeline
> handler from scratch, implementing a PipelineHandlerVivid for the
> virtual video test driver provided by the kernel. The aim of this guide
> is to provide readers with a full walkthrough of the various functions
> which must be impelmented when writing a new pipeline handler, and can
> be followed without having a real device available (however the 'vivid'
> module must be provided by your kernel or distribution).
> 
> The Application writers guide discusses key aspects as the reader
> implements a basic application to use the CameraManager to obtain a
> camera, configure it, and capture frames.
> 
> An IPA writers guide is expected in the near future, but due to the
> current activity and changes ongoing with the IPA API, that will be
> provided after the current work activity with IPC has settled.
> 
> These guides are not yet built by the libcamera.org website (further
> refactoring and organising will happen first), but are integrated into
> any local build which can be generated with Sphinx during the normal
> libcamera build process.
> 
> Further expansion to all of these documents is also likely, but I hope
> to integrate these in their current form and build on top.

This all looks good to me. I'll go through the individual patches, with
the mindset of fixing issues on top whenever possible to minimize the
bikeshedding delay.

> Chris Chinchilla (3):
>   Documentation: Guides: Developers Guide to Libcamera
>   Documentation: Guides: Pipeline Handler Writers Guide
>   Documentation: Guides: Application Writers Guide
> 
>  .../guides/application-developer.rst          |  644 +++++++
>  Documentation/guides/introduction.rst         |  319 ++++
>  Documentation/guides/pipeline-handler.rst     | 1473 +++++++++++++++++
>  Documentation/index.rst                       |    4 +
>  Documentation/meson.build                     |    3 +
>  5 files changed, 2443 insertions(+)
>  create mode 100644 Documentation/guides/application-developer.rst
>  create mode 100644 Documentation/guides/introduction.rst
>  create mode 100644 Documentation/guides/pipeline-handler.rst

Hi Laurent,

On 20/08/2020 16:35, Laurent Pinchart wrote:
> Hi Kieran,
> 
> Thank you for these long awaited patches :-)

Documentation is hard and slow ;-)

> 
> On Thu, Aug 20, 2020 at 02:47:48PM +0100, Kieran Bingham wrote:
>> Hi All,
>>
>> Here is the culmination of work from Chris, Jacopo and Myself preparing
>> some developer guides for libcamera. This is marked as v4, as they are
>> based upon earlier versions of work previously posted by Chris.
>>
>> These three guides aim to cover detail across the areas that a developer
>> wanting to make use of libcamera would look at, including a dedicated
>> walkthrough of the steps of creating a new pipeline handler, or a user
>> application which will make use of libcamera to capture frames.
>>
>> The guides start with an introduction and overview, which replicates
>> quite a bit from the existing "Docs" page, but forms part of refactoring
>> that documentation.
>>
>> The Pipeline handler guide walks through the creation of a new pipeline
>> handler from scratch, implementing a PipelineHandlerVivid for the
>> virtual video test driver provided by the kernel. The aim of this guide
>> is to provide readers with a full walkthrough of the various functions
>> which must be impelmented when writing a new pipeline handler, and can
>> be followed without having a real device available (however the 'vivid'
>> module must be provided by your kernel or distribution).
>>
>> The Application writers guide discusses key aspects as the reader
>> implements a basic application to use the CameraManager to obtain a
>> camera, configure it, and capture frames.
>>
>> An IPA writers guide is expected in the near future, but due to the
>> current activity and changes ongoing with the IPA API, that will be
>> provided after the current work activity with IPC has settled.
>>
>> These guides are not yet built by the libcamera.org website (further
>> refactoring and organising will happen first), but are integrated into
>> any local build which can be generated with Sphinx during the normal
>> libcamera build process.
>>
>> Further expansion to all of these documents is also likely, but I hope
>> to integrate these in their current form and build on top.
> 
> This all looks good to me. I'll go through the individual patches, with
> the mindset of fixing issues on top whenever possible to minimize the
> bikeshedding delay.

Feel free to also submit a patch on top if you make changes locally as
you are going through it ;-)

--
Kieran


> 
>> Chris Chinchilla (3):
>>   Documentation: Guides: Developers Guide to Libcamera
>>   Documentation: Guides: Pipeline Handler Writers Guide
>>   Documentation: Guides: Application Writers Guide
>>
>>  .../guides/application-developer.rst          |  644 +++++++
>>  Documentation/guides/introduction.rst         |  319 ++++
>>  Documentation/guides/pipeline-handler.rst     | 1473 +++++++++++++++++
>>  Documentation/index.rst                       |    4 +
>>  Documentation/meson.build                     |    3 +
>>  5 files changed, 2443 insertions(+)
>>  create mode 100644 Documentation/guides/application-developer.rst
>>  create mode 100644 Documentation/guides/introduction.rst
>>  create mode 100644 Documentation/guides/pipeline-handler.rst
>