libcamera  v0.3.0
Supporting cameras in Linux since 2019
Public Member Functions | Public Attributes | Protected Member Functions | Friends | List of all members
libcamera::MediaDevice Class Reference

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

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

Public Member Functions

 MediaDevice (const std::string &deviceNode)
 Construct a MediaDevice. More...
 
bool acquire ()
 Claim a device for exclusive use. More...
 
void release ()
 Release a device previously claimed for exclusive use. More...
 
bool busy () const
 Check if a device is in use. More...
 
bool lock ()
 Lock the device to prevent it from being used by other instances of libcamera. More...
 
void unlock ()
 Unlock the device and free it for use for libcamera instances. More...
 
int populate ()
 Populate the MediaDevice with device information and media objects. More...
 
bool isValid () const
 Query whether the media graph has been populated and is valid. More...
 
const std::string & driver () const
 Retrieve the media device driver name. More...
 
const std::string & deviceNode () const
 Retrieve the media device node path. More...
 
const std::string & model () const
 Retrieve the media device model name. More...
 
unsigned int version () const
 Retrieve the media device API version. More...
 
unsigned int hwRevision () const
 Retrieve the media device hardware revision. More...
 
const std::vector< MediaEntity * > & entities () const
 Retrieve the list of entities in the media graph. More...
 
MediaEntitygetEntityByName (const std::string &name) const
 Return the MediaEntity with name name. More...
 
MediaLinklink (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. More...
 
MediaLinklink (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. More...
 
MediaLinklink (const MediaPad *source, const MediaPad *sink)
 Retrieve the MediaLink that connects two pads. More...
 
int disableLinks ()
 Disable all links in the media device. More...
 

Public Attributes

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

Protected Member Functions

std::string logPrefix () const override
 Retrieve a string to be prefixed to the log message. More...
 
- 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. More...
 

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]deviceNodeThe 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()

◆ busy()

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()

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()

libcamera::MediaDevice::driver ( ) const
inline

Retrieve the media device driver name.

Returns
The name of the kernel driver that handles the MediaDevice

◆ entities()

libcamera::MediaDevice::entities ( ) const
inline

Retrieve the list of entities in the media graph.

Returns
The list of MediaEntities registered in the MediaDevice

◆ getEntityByName()

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

Return the MediaEntity with name name.

Parameters
[in]nameThe entity name
Returns
The entity with name, or nullptr if no such entity is found

◆ hwRevision()

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()

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 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]sourceNameThe source entity name
[in]sourceIdxThe index of the source pad
[in]sinkNameThe sink entity name
[in]sinkIdxThe 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

◆ link() [2/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]sourceThe source entity
[in]sourceIdxThe index of the source pad
[in]sinkThe sink entity
[in]sinkIdxThe 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() [3/3]

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

Retrieve the MediaLink that connects two pads.

Parameters
[in]sourceThe source pad
[in]sinkThe 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

◆ 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()

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()

◆ 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()

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

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: