libcamera: libcamera::MediaDevice Class Reference

libcamera v0.7.0 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::MediaDevice Class Reference

The MediaDevice represents a Media Controller device with its full graph of connected objects. More...

Inheritance diagram for libcamera::MediaDevice:
[legend]
Collaboration diagram for libcamera::MediaDevice:
[legend]

## Public Member Functions
| MediaDevice (const std::string &deviceNode)
| Construct a MediaDevice.
bool | acquire ()
| Claim a device for exclusive use.
void | release ()
| Release a device previously claimed for exclusive use.
bool | busy () const
| Check if a device is in use.
bool | lock ()
| Lock the device to prevent it from being used by other instances of libcamera.
void | unlock ()
| Unlock the device and free it for use for libcamera instances.
int | populate ()
| Populate the MediaDevice with device information and media objects.
bool | isValid () const
| Query whether the media graph has been populated and is valid.
const std::string & | driver () const
| Retrieve the media device driver name.
const std::string & | deviceNode () const
| Retrieve the media device node path.
const std::string & | model () const
| Retrieve the media device model name.
unsigned int | version () const
| Retrieve the media device API version.
unsigned int | hwRevision () const
| Retrieve the media device hardware revision.
const std::vector< MediaEntity * > & | entities () const
| Retrieve the list of entities in the media graph.
MediaEntity * | getEntityByName (const std::string &name) const
| Return the MediaEntity with name name.
MediaEntity * | getEntityByName (const std::regex &name) const
| Return the MediaEntity with name matching the regex name.
MediaLink * | link (const std::string &sourceName, unsigned int sourceIdx, const std::string &sinkName, unsigned int sinkIdx)
| Retrieve the MediaLink connecting two pads, identified by entity names and pad indexes.
MediaLink * | link (const MediaEntity *source, unsigned int sourceIdx, const MediaEntity *sink, unsigned int sinkIdx)
| Retrieve the MediaLink connecting two pads, identified by the entities they belong to and pad indexes.
MediaLink * | link (const MediaPad *source, const MediaPad *sink)
| Retrieve the MediaLink that connects two pads.
int | disableLinks ()
| Disable all links in the media device.
std::vector< MediaEntity * > | locateEntities (unsigned int function)
| Identify all entities of a common function in the MediaDevice.
int | allocateRequests (unsigned int count, std::vector< std::unique_ptr< V4L2Request > > *requests)
| Allocate requests.
bool | supportsRequests ()
| Check if requests are supported.

## Public Attributes
Signal | disconnected
| Signal emitted when the media device is disconnected from the system.

## Protected Member Functions
std::string | logPrefix () const override
| Retrieve a string to be prefixed to the log message.
Protected Member Functions inherited from libcamera::Loggable
LogMessage | _log (const LogCategory &category, LogSeverity severity, const char *fileName=__builtin_FILE(), unsigned int line=__builtin_LINE()) const
| Create a temporary LogMessage object to log a message.

## Friends
int | MediaLink::setEnabled (bool enable)

## Detailed Description

The MediaDevice represents a Media Controller device with its full graph of connected objects.

A MediaDevice instance is associated with a media controller device node when created, and that association is kept for the lifetime of the MediaDevice instance.

The instance is created with an empty media graph. Before performing any other operation, it must be populate by calling populate(). Instances of MediaEntity, MediaPad and MediaLink are created to model the media graph, and stored in a map indexed by object id.

The graph is valid once successfully populated, as reported by the isValid() function. It can be queried to list all entities(), or entities can be looked up by name with getEntityByName(). The graph can be traversed from entity to entity through pads and links as exposed by the corresponding classes.

Media devices can be claimed for exclusive use with acquire(), released with release() and tested with busy(). This mechanism is aimed at pipeline managers to claim media devices they support during enumeration.

## Constructor & Destructor Documentation

## ◆ MediaDevice()

libcamera::MediaDevice::MediaDevice | ( | const std::string & | deviceNode | ) |

Construct a MediaDevice.

Parameters

  [in] | deviceNode | The media device node path

Once constructed the media device is invalid, and must be populated with populate() before the media graph can be queried.

## Member Function Documentation

## ◆ acquire()

bool libcamera::MediaDevice::acquire | ( |  | ) |

Claim a device for exclusive use.

The device claiming mechanism offers simple media device access arbitration between multiple users. When the media device is created, it is available to all users. Users can query the media graph to determine whether they can support the device and, if they do, claim the device for exclusive use. Other users are then expected to skip over media devices in use as reported by the busy() function.

Once claimed the device shall be released by its user when not needed anymore by calling the release() function. Acquiring the media device opens a file descriptor to the device which is kept open until release() is called.

Exclusive access is only guaranteed if all users of the media device abide by the device claiming mechanism, as it isn't enforced by the media device itself.

Returns
  true if the device was successfully claimed, or false if it was already in use

See also
  release(), busy()

## ◆ allocateRequests()

int libcamera::MediaDevice::allocateRequests | ( | unsigned int | count,
|  | std::vector< std::unique_ptr< V4L2Request > > * | requests )

Allocate requests.

Parameters

  [in] | count | Number of requests to allocate
  [out] | requests | Vector to store allocated requests

Allocates and stores count requests in requests. If allocation fails, an error is returned and requests is cleared.

Returns
  0 on success or a negative error code otherwise

## ◆ busy()

bool libcamera::MediaDevice::busy | ( |  | ) | const
| inline

Check if a device is in use.

Returns
  true if the device has been claimed for exclusive use, or false if it is available

See also
  acquire(), release()

## ◆ deviceNode()

const std::string & libcamera::MediaDevice::deviceNode | ( |  | ) | const
| inline

Retrieve the media device node path.

Returns
  The MediaDevice deviceNode path

## ◆ disableLinks()

int libcamera::MediaDevice::disableLinks | ( |  | ) |

Disable all links in the media device.

Disable all the media device links, clearing the MEDIA_LNK_FL_ENABLED flag on links which are not flagged as IMMUTABLE.

Returns
  0 on success or a negative error code otherwise

## ◆ driver()

const std::string & libcamera::MediaDevice::driver | ( |  | ) | const
| inline

Retrieve the media device driver name.

Returns
  The name of the kernel driver that handles the MediaDevice

## ◆ entities()

const std::vector< MediaEntity * > & libcamera::MediaDevice::entities | ( |  | ) | const
| inline

Retrieve the list of entities in the media graph.

Returns
  The list of MediaEntities registered in the MediaDevice

## ◆ getEntityByName() [1/2]

MediaEntity * libcamera::MediaDevice::getEntityByName | ( | const std::regex & | name | ) | const

Return the MediaEntity with name matching the regex name.

Parameters

  [in] | name | A regex to match the entity name

Returns
  The entity matching the regex name, or nullptr if no such entity is found or multiple entities match on name

## ◆ getEntityByName() [2/2]

MediaEntity * libcamera::MediaDevice::getEntityByName | ( | const std::string & | name | ) | const

Return the MediaEntity with name name.

Parameters

  [in] | name | The entity name

Returns
  The entity with name, or nullptr if no such entity is found

## ◆ hwRevision()

unsigned int libcamera::MediaDevice::hwRevision | ( |  | ) | const
| inline

Retrieve the media device hardware revision.

The hardware revision is in a driver-specific format.

Returns
  The MediaDevice hardware revision

## ◆ isValid()

bool libcamera::MediaDevice::isValid | ( |  | ) | const
| inline

Query whether the media graph has been populated and is valid.

Returns
  true if the media graph is valid, false otherwise

## ◆ link() [1/3]

MediaLink * libcamera::MediaDevice::link | ( | const MediaEntity * | source,
|  | unsigned int | sourceIdx,
|  | const MediaEntity * | sink,
|  | unsigned int | sinkIdx )

Retrieve the MediaLink connecting two pads, identified by the entities they belong to and pad indexes.

Parameters

  [in] | source | The source entity
  [in] | sourceIdx | The index of the source pad
  [in] | sink | The sink entity
  [in] | sinkIdx | The index of the sink pad

Find the link that connects the pads at index sourceIdx of the source entity source, to the pad at index sinkIdx of the sink entity sink, if any.

See also
  link(const std::string &sourceName, unsigned int sourceIdx, const std::string &sinkName, unsigned int sinkIdx)
  link(const MediaPad *source, const MediaPad *sink)

Returns
  The link that connects the two pads, or nullptr if no such a link exists

## ◆ link() [2/3]

MediaLink * libcamera::MediaDevice::link | ( | const MediaPad * | source,
|  | const MediaPad * | sink )

Retrieve the MediaLink that connects two pads.

Parameters

  [in] | source | The source pad
  [in] | sink | The sink pad

See also
  link(const std::string &sourceName, unsigned int sourceIdx, const std::string &sinkName, unsigned int sinkIdx)
  link(const MediaEntity *source, unsigned int sourceIdx, const MediaEntity *sink, unsigned int sinkIdx)

Returns
  The link that connects the two pads, or nullptr if no such a link exists

## ◆ link() [3/3]

MediaLink * libcamera::MediaDevice::link | ( | const std::string & | sourceName,
|  | unsigned int | sourceIdx,
|  | const std::string & | sinkName,
|  | unsigned int | sinkIdx )

Retrieve the MediaLink connecting two pads, identified by entity names and pad indexes.

Parameters

  [in] | sourceName | The source entity name
  [in] | sourceIdx | The index of the source pad
  [in] | sinkName | The sink entity name
  [in] | sinkIdx | The index of the sink pad

Find the link that connects the pads at index sourceIdx of the source entity with name sourceName, to the pad at index sinkIdx of the sink entity with name sinkName, if any.

See also
  link(const MediaEntity *source, unsigned int sourceIdx, const MediaEntity *sink, unsigned int sinkIdx)
  link(const MediaPad *source, const MediaPad *sink)

Returns
  The link that connects the two pads, or nullptr if no such a link exists

## ◆ locateEntities()

std::vector< MediaEntity * > libcamera::MediaDevice::locateEntities | ( | unsigned int | function | ) |

Identify all entities of a common function in the MediaDevice.

Parameters

  [in] | function | The entity function to search for

Search all entities within the graph of the MediaDevice and return a vector of those which match the given function.

Returns
  A vector of matching entities

## ◆ lock()

bool libcamera::MediaDevice::lock | ( |  | ) |

Lock the device to prevent it from being used by other instances of libcamera.

Multiple instances of libcamera might be running on the same system, at the same time. To allow the different instances to coexist, system resources in the form of media devices must be accessible for enumerating the cameras they provide at all times, while still allowing an instance to lock a resource while it prepares to actively use a camera from the resource.

This function shall not be called from a pipeline handler implementation directly, as the base PipelineHandler implementation handles this on the behalf of the specified implementation.

Returns
  True if the device could be locked, false otherwise

See also
  unlock()

## ◆ logPrefix()

std::string libcamera::MediaDevice::logPrefix | ( |  | ) | const
| overrideprotectedvirtual

Retrieve a string to be prefixed to the log message.

This function allows classes inheriting from the Loggable class to extend the logger with an object-specific prefix output right before the log message contents.

Returns
  A string to be prefixed to the log message

Implements libcamera::Loggable.

## ◆ model()

const std::string & libcamera::MediaDevice::model | ( |  | ) | const
| inline

Retrieve the media device model name.

Returns
  The MediaDevice model name

## ◆ populate()

int libcamera::MediaDevice::populate | ( |  | ) |

Populate the MediaDevice with device information and media objects.

This function retrieves the media device information and enumerates all media objects in the media device graph and creates their MediaObject representations. All entities, pads and links are stored as MediaEntity, MediaPad and MediaLink respectively, with cross-references between objects. Interfaces are not processed.

Entities are stored in a separate list in the MediaDevice to ease lookup, while pads are accessible from the entity they belong to and links from the pads they connect.

Returns
  0 on success or a negative error code otherwise

## ◆ release()

void libcamera::MediaDevice::release | ( |  | ) |

Release a device previously claimed for exclusive use.

See also
  acquire(), busy()

## ◆ supportsRequests()

bool libcamera::MediaDevice::supportsRequests | ( |  | ) |

Check if requests are supported.

Checks if the device supports V4L2 requests by trying to allocate a single request. The result is cached, so the allocation is only tried once.

Returns
  True if the device supports requests, false otherwise

## ◆ unlock()

void libcamera::MediaDevice::unlock | ( |  | ) |

Unlock the device and free it for use for libcamera instances.

This function shall not be called from a pipeline handler implementation directly, as the base PipelineHandler implementation handles this on the behalf of the specified implementation.

See also
  lock()

## ◆ version()

unsigned int libcamera::MediaDevice::version | ( |  | ) | const
| inline

Retrieve the media device API version.

The version is formatted with the KERNEL_VERSION() macro.

Returns
  The MediaDevice API version

## Member Data Documentation

## ◆ disconnected

Signal libcamera::MediaDevice::disconnected

Signal emitted when the media device is disconnected from the system.

This signal is emitted when the device enumerator detects that the media device has been removed from the system. For hot-pluggable devices this is usually caused by physical device disconnection, but can also result from driver unloading for most devices. The media device is passed as a parameter.

The documentation for this class was generated from the following files:

- include/libcamera/internal/media_device.h
- src/libcamera/media_device.cpp