libcamera::Buffer Class Reference

A buffer handle and dynamic metadata. More...

Public Types
enum	Status { BufferSuccess, BufferError, BufferCancelled }

Public Member Functions
	Buffer (unsigned int index=-1, const Buffer *metadata=nullptr)
	Construct a buffer not associated with any stream. More...
	Buffer (const Buffer &)=delete
Buffer &	operator= (const Buffer &)=delete
unsigned int	index () const
	Retrieve the Buffer index. More...
const std::array< int, 3 > &	dmabufs () const
	Retrieve the dmabuf file descriptors for all buffer planes. More...
BufferMemory *	mem ()
	Retrieve the BufferMemory this buffer is associated with. More...
unsigned int	bytesused () const
	Retrieve the number of bytes occupied by the data in the buffer. More...
uint64_t	timestamp () const
	Retrieve the time when the buffer was processed. More...
unsigned int	sequence () const
	Retrieve the buffer sequence number. More...
Status	status () const
	Retrieve the buffer status. More...
Request *	request () const
	Retrieve the request this buffer belongs to. More...
Stream *	stream () const
	Retrieve the stream this buffer is associated with. More...

Friends
class	Camera
class	Request
class	Stream
class	V4L2VideoDevice

Detailed Description

A buffer handle and dynamic metadata.

The Buffer class references a buffer memory and associates dynamic metadata related to the frame contained in the buffer. It allows referencing buffer memory through a single interface regardless of whether the memory is allocated internally in libcamera or provided externally through dmabuf.

Buffer instances are allocated dynamically for a stream through Stream::createBuffer(), added to a request with Request::addBuffer() and deleted automatically after the request complete handler returns.

Member Enumeration Documentation

Status

enum libcamera::Buffer::Status

Buffer completion status

Enumerator
BufferSuccess	The buffer has completed with success and contains valid data. All its other metadata (such as bytesused(), timestamp() or sequence() number) are valid.
BufferError	The buffer has completed with an error and doesn't contain valid data. Its other metadata are valid.
BufferCancelled	The buffer has been cancelled due to capture stop. Its other metadata are invalid and shall not be used.

Constructor & Destructor Documentation

Buffer()

libcamera::Buffer::Buffer	(	unsigned int	index = -1,
		const Buffer *	metadata = nullptr
	)

Construct a buffer not associated with any stream.

This method constructs an orphaned buffer not associated with any stream. It is not meant to be called by applications, they should instead create buffers for a stream with Stream::createBuffer().

Member Function Documentation

bytesused()

libcamera::Buffer::bytesused ( ) const

inline

Retrieve the number of bytes occupied by the data in the buffer.

Returns

Number of bytes occupied in the buffer

dmabufs()

libcamera::Buffer::dmabufs ( ) const

inline

Retrieve the dmabuf file descriptors for all buffer planes.

The dmabufs array contains one dmabuf file descriptor per plane. Unused entries are set to -1.

Returns

The dmabuf file descriptors

index()

libcamera::Buffer::index ( ) const

inline

Retrieve the Buffer index.

Returns

The buffer index

mem()

libcamera::Buffer::mem ( )

inline

Retrieve the BufferMemory this buffer is associated with.

The association between the buffer and a BufferMemory instance is valid from the time the request containing this buffer is queued to a camera to the end of that request's completion handler.

Returns

The BufferMemory this buffer is associated with

request()

libcamera::Buffer::request ( ) const

inline

Retrieve the request this buffer belongs to.

The intended callers of this method are buffer completion handlers that need to associate a buffer to the request it belongs to.

A Buffer is associated to a request by Request::prepare() and the association is valid until the buffer completes. The returned request pointer is valid only during that interval.

Returns

The Request the Buffer belongs to, or nullptr if the buffer is either completed or not associated with a request

See also

Buffer::setRequest()

sequence()

libcamera::Buffer::sequence ( ) const

inline

Retrieve the buffer sequence number.

The sequence number is a monotonically increasing number assigned to the buffer processed by the stream. Gaps in the sequence numbers indicate dropped frames.

Returns

Sequence number of the buffer

status()

libcamera::Buffer::status ( ) const

inline

Retrieve the buffer status.

The buffer status reports whether the buffer has completed successfully (BufferSuccess) or if an error occurred (BufferError).

Returns

The buffer status

stream()

libcamera::Buffer::stream ( ) const

inline

Retrieve the stream this buffer is associated with.

A Buffer is associated to the stream that created it with Stream::createBuffer() and the association is valid until the buffer is destroyed. Buffer instances that are created directly are not associated with any stream.

Returns

The Stream the Buffer is associated with, or nullptr if the buffer is not associated with a stream

timestamp()

libcamera::Buffer::timestamp ( ) const

inline

Retrieve the time when the buffer was processed.

The timestamp is expressed as a number of nanoseconds since the epoch.

Returns

Timestamp when the buffer was processed

---

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

• include/libcamera/buffer.h
• src/libcamera/buffer.cpp