ImageBuffer Class Reference

Represents an image buffer. More...

Classes

struct   MetaData

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]ptrPointer to the image data as passed as data into wrapMemory
[in]bufferSizeBuffer 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
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]errReference 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]bufferSource buffer to copy from
[in]optionsA bitwise combination of CopyOptions to customize the copy operation
[out]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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:

Parameters
[in]dataPointer to a region of memory to be used as image data by the image buffer object
[in]bufferSizeSize of the region of memory pointed to by data
[in]pitchDifference between memory addresses of two consecutive lines of image data
[in]imageTypeType of image to be stored in the image buffer
[in]on_releaseOptional 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]errReference to an error handler. See Error Handling for details.
Returns
The new image buffer, or nullptr if an error occurs.