ImageBuffer Class Reference

Represents an image buffer. More...

Classes

struct

A structure containing frame metadata. More...

Public Types

enum class	CopyOptions : int { Default = 0 , SkipImage = c_interface::IC4_IMAGEBUFFER_COPY_SKIP_IMAGE , SkipChunkData = c_interface::IC4_IMAGEBUFFER_COPY_SKIP_CHUNKDATA } Contains options to configure the behavior of ImageBuffer::copyFrom(). More...
using	ReleaseMemoryHandler = std::function< void(void *ptr, size_t bufferSize)> Defines a callback function to be called when an image buffer created by ImageBuffer::wrapMemory is destroyed and the image data will no longer be accessed through it.

Public Member Functions

const ImageType &	imageType (Error &err=Error::Default()) const Queries information about the image buffers's image data type.
void *	ptr (Error &err=Error::Default()) const Returns a pointer to the data managed by the image buffer.
size_t	bufferSize (Error &err=Error::Default()) const Returns the size of the image buffer.
ptrdiff_t	pitch (Error &err=Error::Default()) const Returns the pitch for the image buffer.
MetaData	metaData (Error &err=Error::Default()) Retrieves frame metadata from an image buffer object.
bool	copyFrom (const ImageBuffer &buffer, CopyOptions options=CopyOptions::Default, Error &err=Error::Default()) Copies the contents of one image buffer to another image buffer.
bool	isWritable () const Checks whether an image buffer object is (safely) writable.

Static Public Member Functions

static std::shared_ptr< ImageBuffer >

wrapMemory (void *data, size_t bufferSize, ptrdiff_t pitch, const ImageType &imageType, ReleaseMemoryHandler on_release={}, Error &err=Error::Default())

Creates an image buffer object using external memory as storage area for the image data.

Detailed Description

Represents an image buffer.

Image buffer objects are created automatically by the various Sink types. They can also be created manually on request by a BufferPool, or by calling ImageBuffer::wrapMemory().

Programs use image buffers via std::shared_ptr<ImageBuffer>. If all pointers are released, the image buffer object is returned to its source for reuse. For example, an image buffer retrieved from QueueSink::popOutputBuffer() will be re-queued.

Member Typedef Documentation

◆ ReleaseMemoryHandler

using ReleaseMemoryHandler = std::function<void(void* ptr, size_t bufferSize)>

Defines a callback function to be called when an image buffer created by ImageBuffer::wrapMemory is destroyed and the image data will no longer be accessed through it.

Parameters

[in]	ptr	Pointer to the image data as passed as data into wrapMemory
[in]	bufferSize	Buffer size as passed as buffer_size into wrapMemory

Member Enumeration Documentation

◆ CopyOptions

enum class CopyOptions : int

strong

Contains options to configure the behavior of ImageBuffer::copyFrom().

Enumerator

Enumerator
Default	Default behavior. Copy image data, meta data and chunk data.
SkipImage	Instructs ImageBuffer::copyFrom() to skip the image data when copying. If included in the `flags` argument, ImageBuffer::copyFrom() only copies the non-image parts of the buffer, and a program-defined algorithm can handle the image copy operation.
SkipChunkData	Instructs ImageBuffer::copyFrom() to not copy the chunk data. This can be useful if the chunk data is large and not required in the destination frame.

Default

Default behavior.

Copy image data, meta data and chunk data.

SkipImage

Instructs ImageBuffer::copyFrom() to skip the image data when copying.

If included in the flags argument, ImageBuffer::copyFrom() only copies the non-image parts of the buffer, and a program-defined algorithm can handle the image copy operation.

SkipChunkData

Instructs ImageBuffer::copyFrom() to not copy the chunk data.

This can be useful if the chunk data is large and not required in the destination frame.

Member Function Documentation

◆ bufferSize()

size_t bufferSize ( Error & err = Error::Default() ) const

inline

Returns the size of the image buffer.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: The size of the image buffer, or 0 if an error occurred.
Check the err output parameter for details.

◆ copyFrom()

bool copyFrom	(	const ImageBuffer &	buffer,
		CopyOptions	options = `CopyOptions::Default`,
		Error &	err = `Error::Default()`
	)

inline

Copies the contents of one image buffer to another image buffer.

Parameters

[in]	buffer	Source buffer to copy from
[in]	options	A bitwise combination of CopyOptions to customize the copy operation
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: true on success, otherwise false.
Check the err output parameter for details.

Remarks: If the pixel format of the images in source and destination is not equal, the image is converted. For example, if the pixel format of source is PixelFormat::BayerRG8 and the pixel format of destination is PixelFormat::BGR8, a demosaicing operation creates a color image.
If flags contains CopyOptions::SkipImage, the function does not copy the image data. The function then only copies the meta data, and a program-defined algorithm can handle the image copy operation.
If flags contains CopyOptions::SkipChunkData, the function does not copy the chunk data contained in source. This can be useful if the chunk data is large and not required.

Note: If the width or height of source and destination are not equal, the function fails and the error value is set to ErrorCode::ConversionNotSupported.
If there is no algorithm available for the requested conversion, the function fails and the error value is set to ErrorCode::ConversionNotSupported.
If the destination image buffer is not writable, the function fails and the error value is set to ErrorCode::InvalidOperation.

◆ imageType()

const ImageType & imageType ( Error & err = Error::Default() ) const

inline

Queries information about the image buffers's image data type.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: The type of image that can be stored in the image buffer.

◆ isWritable()

bool isWritable ( ) const

inline

Checks whether an image buffer object is (safely) writable.

In some situations, image buffer objects are shared between the application holding a handle to the image buffer object and the library. For example, the image buffer might be shared with a display or a video writer.

A shared buffer is not safely writable. Writing to a buffer that is shared can lead to unexpected behavior, for example a modification may partially appear in the result of an operation that is happening in parallel.

Passing the image buffer into a function such as Display::displayBuffer() or VideoWriter::addFrame() can lead to a buffer becoming shared.

Returns: true if the image buffer is not shared with any part of the library, and is therefore safely writable.
false, if the image buffer is shared and therefore should not be written into.

◆ metaData()

MetaData metaData ( Error & err = Error::Default() )

inline

Retrieves frame metadata from an image buffer object.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: A MetaData structur containing frame metadata

◆ pitch()

ptrdiff_t pitch ( Error & err = Error::Default() ) const

inline

Returns the pitch for the image buffer.

The pitch is the distance between the starting memory location of two consecutive lines.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: The pitch of the image buffer, or 0 if an error occurred.
Check the err output parameter for details.

◆ ptr()

void * ptr ( Error & err = Error::Default() ) const

inline

Returns a pointer to the data managed by the image buffer.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: A pointer to the image data, or nullptr if an error occurred.
Check the err output parameter for details.

Remarks: The memory pointed to by the returned pointer is valid as long as the image buffer object exists.

◆ wrapMemory()

static std::shared_ptr< ImageBuffer > wrapMemory	(	void *	data,
		size_t	bufferSize,
		ptrdiff_t	pitch,
		const ImageType &	imageType,
		ReleaseMemoryHandler	on_release = `{}`,
		Error &	err = `Error::Default()`
	)

inlinestatic

Creates an image buffer object using external memory as storage area for the image data.

This function can be useful when copying image data into buffers of third-party libraries:

Create an image object in the third-party library
Wrap the third-party library's image data into an ImageBuffer using ImageBuffer::wrapMemory().
Copy the data from an existing image buffer object into the third-party image buffer using ImageBuffer::copyFrom().

Parameters

[in]	data	Pointer to a region of memory to be used as image data by the image buffer object
[in]	bufferSize	Size of the region of memory pointed to by data
[in]	pitch	Difference between memory addresses of two consecutive lines of image data
[in]	imageType	Type of image to be stored in the image buffer
[in]	on_release	Optional callback function to be called when the image buffer object is destroyed. This can be useful when the program needs to keep track of the memory pointer to by the image buffer and has to release it once the image buffer object no longer exists. The lifetime of the image buffer can potentially be extended beyond the existance of its handle when it is shared with API functions, e.g. Display::displayBuffer or VideoWriter::addFrame.
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: The new image buffer, or nullptr if an error occurs.