Image Buffers

Data Structures

Image data is passed around in image buffer objects (IC4_IMAGE_BUFFER). More...

struct   IC4_ALLOCATOR_CALLBACKS

Contains function pointers used to configure a custom allocator for image buffers. More...
struct  IC4_BUFFER_POOL_CONFIG

Configures the behavior of a IC4_BUFFER_POOL. More...
struct  IC4_BUFFERPOOL_ALLOCATION_OPTIONS

Contains options to configure the allocation when requesting an image buffer from a buffer pool. More...
struct  IC4_FRAME_METADATA

A structure containing frame metadata. More...
struct  IC4_IMAGE_TYPE

Represents an image type, including pixel format and image dimensions. More...
struct  IC4_BUFFER_POOL

The buffer pool allows allocating additional image buffers for use by the program. More...
struct  IC4_IMAGE_BUFFER

Represents an image buffer. More...

Typedefs

typedef void(* ic4_imagebuffer_memory_release) (void *ptr, size_t buffer_size, void *user_ptr)

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

Enumerations

enum   IC4_IMAGEBUFFER_COPY_FLAGS { IC4_IMAGEBUFFER_COPY_SKIP_IMAGE = 1 , IC4_IMAGEBUFFER_COPY_SKIP_CHUNKDATA = 2 }

Contains options to configure the behavior of ic4_imagebuffer_copy(). More...
enum   IC4_PIXEL_FORMAT {
  IC4_PIXEL_FORMAT_Unspecified = 0 , IC4_PIXEL_FORMAT_Mono8 = 0x01080001 , IC4_PIXEL_FORMAT_Mono10p = 0x010A0046 , IC4_PIXEL_FORMAT_Mono12p = 0x010C0047 ,
  IC4_PIXEL_FORMAT_Mono16 = 0x01100007 , IC4_PIXEL_FORMAT_BayerBG8 = 0x0108000B , IC4_PIXEL_FORMAT_BayerBG10p = 0x010A0052 , IC4_PIXEL_FORMAT_BayerBG12p = 0x010C0053 ,
  IC4_PIXEL_FORMAT_BayerBG16 = 0x01100031 , IC4_PIXEL_FORMAT_BayerGB8 = 0x0108000A , IC4_PIXEL_FORMAT_BayerGB10p = 0x010A0054 , IC4_PIXEL_FORMAT_BayerGB12p = 0x010C0055 ,
  IC4_PIXEL_FORMAT_BayerGB16 = 0x01100030 , IC4_PIXEL_FORMAT_BayerGR8 = 0x01080008 , IC4_PIXEL_FORMAT_BayerGR10p = 0x010A0056 , IC4_PIXEL_FORMAT_BayerGR12p = 0x010C0057 ,
  IC4_PIXEL_FORMAT_BayerGR16 = 0x0110002E , IC4_PIXEL_FORMAT_BayerRG8 = 0x01080009 , IC4_PIXEL_FORMAT_BayerRG10p = 0x010A0058 , IC4_PIXEL_FORMAT_BayerRG12p = 0x010C0059 ,
  IC4_PIXEL_FORMAT_BayerRG16 = 0x0110002F , IC4_PIXEL_FORMAT_BGRa8 = 0x02200017 , IC4_PIXEL_FORMAT_BGRa16 = 0x02400051 , IC4_PIXEL_FORMAT_BGR8 = 0x02180015 ,
  IC4_PIXEL_FORMAT_Mono12Packed = 0x010C0006 , IC4_PIXEL_FORMAT_BayerBG12Packed = 0x010C002D , IC4_PIXEL_FORMAT_BayerGB12Packed = 0x010C002C , IC4_PIXEL_FORMAT_BayerGR12Packed = 0x010C002A ,
  IC4_PIXEL_FORMAT_BayerRG12Packed = 0x010C002B , IC4_PIXEL_FORMAT_YUV422_8 = 0x02100032 , IC4_PIXEL_FORMAT_YCbCr422_8 = 0x0210003B , IC4_PIXEL_FORMAT_YCbCr411_8_CbYYCrYY = 0x020C003C ,
  IC4_PIXEL_FORMAT_YCbCr411_8 = 0x020C005A , IC4_PIXEL_FORMAT_AnyBayer8 = (int)0x8108FF01 , IC4_PIXEL_FORMAT_AnyBayer10p = (int)0x810AFF01 , IC4_PIXEL_FORMAT_AnyBayer12p = (int)0x810CFF01 ,
  IC4_PIXEL_FORMAT_AnyBayer16 = (int)0x8110FF01 , IC4_PIXEL_FORMAT_Invalid = -1
}

The pixel format defines the representation of pixels in an image. More...

Functions

bool  ic4_bufferpool_create (struct IC4_BUFFER_POOL **ppPool, const struct IC4_BUFFER_POOL_CONFIG *config)

Creates a new buffer pool.
struct IC4_BUFFER_POOL * ic4_bufferpool_ref (struct IC4_BUFFER_POOL *pPool)

Increases the buffer pool's internal reference count by one.
void ic4_bufferpool_unref (struct IC4_BUFFER_POOL *pPool)

Decreases the pool's internal reference count by one.

bool ic4_bufferpool_get_buffer (struct IC4_BUFFER_POOL *pPool, const struct IC4_IMAGE_TYPE *image_type, const struct IC4_BUFFERPOOL_ALLOCATION_OPTIONS *options, struct IC4_IMAGE_BUFFER **ppImageBuffer)

Gets a buffer from the buffer pool.

struct IC4_IMAGE_BUFFER * ic4_imagebuffer_ref (struct IC4_IMAGE_BUFFER *pImageBuffer)

Increases the image buffer's internal reference count by one.
void ic4_imagebuffer_unref (struct IC4_IMAGE_BUFFER *pImageBuffer)

Decreases the image buffer's internal reference count by one.
void * ic4_imagebuffer_get_ptr (const struct IC4_IMAGE_BUFFER *pImageBuffer)

Returns a pointer to the data managed by the image buffer.
ptrdiff_t ic4_imagebuffer_get_pitch (const struct IC4_IMAGE_BUFFER *pImageBuffer)

Returns the pitch for the image buffer.

size_t ic4_imagebuffer_get_buffer_size (const struct IC4_IMAGE_BUFFER *pImageBuffer)

Returns the size of the image buffer.

bool ic4_imagebuffer_get_image_type (const struct IC4_IMAGE_BUFFER *pImageBuffer, struct IC4_IMAGE_TYPE *image_type)

Queries information about the image buffers's image data type.
bool ic4_imagebuffer_get_metadata (const struct IC4_IMAGE_BUFFER *pImageBuffer, struct IC4_FRAME_METADATA *metadata)

Retrieves metadata from an image buffer object.
bool ic4_imagebuffer_copy (const struct IC4_IMAGE_BUFFER *source, struct IC4_IMAGE_BUFFER *destination, unsigned int flags)

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

bool ic4_imagebuffer_is_writable (const struct IC4_IMAGE_BUFFER *buffer)

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

bool ic4_imagebuffer_wrap_memory (struct IC4_IMAGE_BUFFER **ppBuffer, void *data, size_t buffer_size, ptrdiff_t pitch, const struct IC4_IMAGE_TYPE *image_type, ic4_imagebuffer_memory_release on_release, void *on_release_user_ptr)

Creates an image buffer object using external memory as storage area for the image data.
const char * ic4_pixelformat_tostring (enum IC4_PIXEL_FORMAT pixel_format)

Returns the name of a pixel format.

size_t ic4_pixelformat_bpp (enum IC4_PIXEL_FORMAT pixel_format)

Returns the bits per pixel of a pixel format.
bool ic4_imagetype_tostring (const struct IC4_IMAGE_TYPE *image_type, char *buffer, size_t *buffer_size)

Convert a given image type into a string representation.

Detailed Description

Image data is passed around in image buffer objects (IC4_IMAGE_BUFFER).

Image buffer objects are created automatically when using one of the various sink types of this library.

Image buffer objects are reference-counted. To share an image buffer object between multiple parts of a program, use ic4_imagebuffer_ref(). Call ic4_imagebuffer_unref() when a reference is no longer required.

If the reference count reaches zero, the image buffer is returned to its source to be reused. For example, an image buffer retrieved from ic4_queuesink_pop_output_buffer() will be re-queued.

Typedef Documentation

◆ ic4_imagebuffer_memory_release

typedef void(* ic4_imagebuffer_memory_release) (void *ptr, size_t buffer_size, void *user_ptr)

Defines a callback function to be called when an image buffer created by ic4_imagebuffer_wrap_memory 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 ic4_imagebuffer_wrap_memory
[in]buffer_sizeBuffer size as passed as buffer_size into ic4_imagebuffer_wrap_memory
[in]user_ptrThe on_release_user_ptr parameter that was specified when the image buffer was created.

Enumeration Type Documentation

◆ IC4_IMAGEBUFFER_COPY_FLAGS

enum IC4_IMAGEBUFFER_COPY_FLAGS

Contains options to configure the behavior of ic4_imagebuffer_copy().

Enumerator
IC4_IMAGEBUFFER_COPY_SKIP_IMAGE 

Instructs ic4_imagebuffer_copy() to skip the image data when copying.

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

IC4_IMAGEBUFFER_COPY_SKIP_CHUNKDATA 

Instructs ic4_imagebuffer_copy() to not copy the chunk data.

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

◆ IC4_PIXEL_FORMAT

enum IC4_PIXEL_FORMAT

The pixel format defines the representation of pixels in an image.

Enumerator
IC4_PIXEL_FORMAT_Unspecified 

Unspecified pixel format, used to partially define a image type.

IC4_PIXEL_FORMAT_Mono8 

Monochrome 8-bit.

IC4_PIXEL_FORMAT_Mono10p 

Monochrome 10-bit packed.

IC4_PIXEL_FORMAT_Mono12p 

Monochrome 12-bit packed.

IC4_PIXEL_FORMAT_Mono16 

Monochrome 16-bit.

IC4_PIXEL_FORMAT_BayerBG8 

Bayer Blue-Green 8-bit.

IC4_PIXEL_FORMAT_BayerBG10p 

Bayer Blue-Green 10-bit packed.

IC4_PIXEL_FORMAT_BayerBG12p 

Bayer Blue-Green 12-bit packed.

IC4_PIXEL_FORMAT_BayerBG16 

Bayer Blue-Green 16-bit.

IC4_PIXEL_FORMAT_BayerGB8 

Bayer Green-Blue 8-bit.

IC4_PIXEL_FORMAT_BayerGB10p 

Bayer Green-Blue 10-bit packed.

IC4_PIXEL_FORMAT_BayerGB12p 

Bayer Green-Blue 12-bit packed.

IC4_PIXEL_FORMAT_BayerGB16 

Bayer Green-Blue 16-bit.

IC4_PIXEL_FORMAT_BayerGR8 

Bayer Green-Red 8-bit.

IC4_PIXEL_FORMAT_BayerGR10p 

Bayer Green-Red 10-bit packed.

IC4_PIXEL_FORMAT_BayerGR12p 

Bayer Green-Red 12-bit packed.

IC4_PIXEL_FORMAT_BayerGR16 

Bayer Green-Red 16-bit.

IC4_PIXEL_FORMAT_BayerRG8 

Bayer Red-Green 8-bit.

IC4_PIXEL_FORMAT_BayerRG10p 

Bayer Red-Green 10-bit packed.

IC4_PIXEL_FORMAT_BayerRG12p 

Bayer Red-Green 12-bit packed.

IC4_PIXEL_FORMAT_BayerRG16 

Bayer Red-Green 16-bit.

IC4_PIXEL_FORMAT_BGRa8 

Blue-Green-Red-alpha 8-bit.

IC4_PIXEL_FORMAT_BGRa16 

Blue-Green-Red-alpha 16-bit.

IC4_PIXEL_FORMAT_BGR8 

Blue-Green-Red 8-bit.

IC4_PIXEL_FORMAT_Mono12Packed 

GigE Vision specific format, Monochrome 12-bit packed.

IC4_PIXEL_FORMAT_BayerBG12Packed 

GigE Vision specific format, Bayer Blue-Green 12-bit packed.

IC4_PIXEL_FORMAT_BayerGB12Packed 

GigE Vision specific format, Bayer Green-Blue 12-bit packed.

IC4_PIXEL_FORMAT_BayerGR12Packed 

GigE Vision specific format, Bayer Green-Red 12-bit packed.

IC4_PIXEL_FORMAT_BayerRG12Packed 

GigE Vision specific format, Bayer Red-Green 12-bit packed.

IC4_PIXEL_FORMAT_YUV422_8 

YUV 4:2:2 8-bit.

IC4_PIXEL_FORMAT_YCbCr422_8 

YCbCr 4:2:2 8-bit.

IC4_PIXEL_FORMAT_YCbCr411_8_CbYYCrYY 

YCbCr 4:1:1 8-bit (CbYYCrYY)

IC4_PIXEL_FORMAT_YCbCr411_8 

YCbCr 4:1:1 8-bit (YYCbYYCr)

IC4_PIXEL_FORMAT_AnyBayer8 

Virtual pixel format value to select any 8-bit bayer format.

When setting the camera's IC4_PROPID_PIXEL_FORMAT to this value, automatically selects one of the 8-bit bayer pixel formats IC4_PIXEL_FORMAT_BayerBG8, IC4_PIXEL_FORMAT_BayerGB8, IC4_PIXEL_FORMAT_BayerRG8 or IC4_PIXEL_FORMAT_BayerGR8.

IC4_PIXEL_FORMAT_AnyBayer10p 

Virtual pixel format value to select any 10-bit packed bayer format.

When setting the camera's IC4_PROPID_PIXEL_FORMAT to this value, automatically selects one of the 10-bit packed bayer pixel formats IC4_PIXEL_FORMAT_BayerBG10p, IC4_PIXEL_FORMAT_BayerGB10p, IC4_PIXEL_FORMAT_BayerRG10p or IC4_PIXEL_FORMAT_BayerGR10p.

IC4_PIXEL_FORMAT_AnyBayer12p 

Virtual pixel format value to select any 12-bit packed bayer format.

When setting the camera's IC4_PROPID_PIXEL_FORMAT to this value, automatically selects one of the 12-bit packed bayer pixel formats IC4_PIXEL_FORMAT_BayerBG12p, IC4_PIXEL_FORMAT_BayerGB12p, IC4_PIXEL_FORMAT_BayerRG12p, IC4_PIXEL_FORMAT_BayerGR12p, IC4_PIXEL_FORMAT_BayerBG12Packed, IC4_PIXEL_FORMAT_BayerGB12Packed, IC4_PIXEL_FORMAT_BayerRG12Packed or IC4_PIXEL_FORMAT_BayerGR12Packed.

IC4_PIXEL_FORMAT_AnyBayer16 

Virtual pixel format value to select any 16-bit bayer format.

When setting the camera's IC4_PROPID_PIXEL_FORMAT to this value, automatically selects one of the 16-bit bayer pixel formats IC4_PIXEL_FORMAT_BayerBG16, IC4_PIXEL_FORMAT_BayerGB16, IC4_PIXEL_FORMAT_BayerRG16 or IC4_PIXEL_FORMAT_BayerGR16.

IC4_PIXEL_FORMAT_Invalid 

Invalid pixel format.

Function Documentation

◆ ic4_bufferpool_create()

bool ic4_bufferpool_create ( struct IC4_BUFFER_POOL **  ppPool,
const struct IC4_BUFFER_POOL_CONFIG *  config 
)

Creates a new buffer pool.

Parameters
[in]ppPoolPointer to a buffer pool handle to receive the new buffer pool. When the buffer pool is no longer required, release the object reference using ic4_bufferpool_unref().
[in]configPointer to a structure containing the buffer pool configuration
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_bufferpool_get_buffer()

bool ic4_bufferpool_get_buffer ( struct IC4_BUFFER_POOL *  pPool,
const struct IC4_IMAGE_TYPE *  image_type,
const struct IC4_BUFFERPOOL_ALLOCATION_OPTIONS *  options,
struct IC4_IMAGE_BUFFER **  ppImageBuffer 
)

Gets a buffer from the buffer pool.

The buffer is either newly allocated, or retrieved from the buffer pool's buffer cache.

Parameters
[in]pPoolA buffer pool
[in]image_typeImage type of the requested buffer
[in]optionsA pointer to a IC4_BUFFERPOOL_ALLOCATION_OPTIONS structure specifying advance allocation options.
May be NULL to use default allocation parameters.
[out]ppImageBufferPointer to an image buffer handle to receive the buffer.
When the buffer is no longer required, release the object reference using ic4_imagebuffer_unref().
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_bufferpool_ref()

struct IC4_BUFFER_POOL * ic4_bufferpool_ref ( struct IC4_BUFFER_POOL *  pPool)

Increases the buffer pool's internal reference count by one.

Parameters
[in]pPoolA pointer to a buffer pool
Returns
The pointer passed via pPool
Remarks
If pPool is NULL, the function returns NULL. An error value is not set.
See also
ic4_bufferpool_unref

◆ ic4_bufferpool_unref()

void ic4_bufferpool_unref ( struct IC4_BUFFER_POOL *  pPool)

Decreases the pool's internal reference count by one.

If the reference count reaches zero, the object is destroyed.

Parameters
[in]pPoolA pointer to a buffer pool
Remarks
If pPool is NULL, the function does nothing. An error value is not set.
See also
ic4_bufferpool_ref

◆ ic4_imagebuffer_copy()

bool ic4_imagebuffer_copy ( const struct IC4_IMAGE_BUFFER *  source,
struct IC4_IMAGE_BUFFER *  destination,
unsigned int  flags 
)

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

Parameters
sourceSource buffer to copy from
destinationDestination buffer to copy into
flagsA bitwise combination of values from IC4_IMAGEBUFFER_COPY_FLAGS.
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 IC4_PIXEL_FORMAT_BayerRG8 and the pixel format of destination is IC4_PIXEL_FORMAT_BGR8, a demosaicing operation creates a color image.
If flags contains IC4_IMAGEBUFFER_COPY_SKIP_IMAGE, 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 IC4_IMAGEBUFFER_COPY_SKIP_CHUNKDATA, 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 IC4_ERROR_CONVERSION_NOT_SUPPORTED.
If there is no algorithm available for the requested conversion, the function fails and the error value is set to IC4_ERROR_CONVERSION_NOT_SUPPORTED.
If the destination frame is not writable, the function fails and the error value is set to IC4_ERROR_INVALID_OPERATION.
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_imagebuffer_get_buffer_size()

size_t ic4_imagebuffer_get_buffer_size ( const struct IC4_IMAGE_BUFFER *  pImageBuffer)

Returns the size of the image buffer.

Parameters
[in]pImageBufferAn image buffer
Returns
The size of this image buffer, or 0 if an error occurred.
Use ic4_get_last_error() to query error information.

◆ ic4_imagebuffer_get_image_type()

bool ic4_imagebuffer_get_image_type ( const struct IC4_IMAGE_BUFFER *  pImageBuffer,
struct IC4_IMAGE_TYPE *  image_type 
)

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

Parameters
[in]pImageBufferAn image buffer
[out]image_typeA IC4_IMAGE_TYPE structure receiving the image data type information.
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_imagebuffer_get_metadata()

bool ic4_imagebuffer_get_metadata ( const struct IC4_IMAGE_BUFFER *  pImageBuffer,
struct IC4_FRAME_METADATA *  metadata 
)

Retrieves metadata from an image buffer object.

Parameters
[in]pImageBufferAn image buffer
[out]metadataA IC4_FRAME_METADATA structure receiving the metadata.
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_imagebuffer_get_pitch()

ptrdiff_t ic4_imagebuffer_get_pitch ( const struct IC4_IMAGE_BUFFER *  pImageBuffer)

Returns the pitch for the image buffer.

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

Parameters
[in]pImageBufferAn image buffer
Returns
The pitch for this image buffer, or 0 if an error occurred.
Use ic4_get_last_error() to query error information.

◆ ic4_imagebuffer_get_ptr()

void * ic4_imagebuffer_get_ptr ( const struct IC4_IMAGE_BUFFER *  pImageBuffer)

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

Parameters
[in]pImageBufferAn image buffer
Returns
A pointer to the image data contained in the image buffer,
or NULL if an error occurred. Use ic4_get_last_error() to query error information.
Remarks
The memory pointed to by the returned pointer is valid as long as the image buffer object exists.

◆ ic4_imagebuffer_is_writable()

bool ic4_imagebuffer_is_writable ( const struct IC4_IMAGE_BUFFER *  buffer)

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 ic4_display_display_buffer() or ic4_videowriter_add_frame() can lead to a buffer becoming shared.

Note
This function only checks for whether the buffer is shared with other parts of the library. It is the program's responsibility
to track whether multiple parts of the program are accessing the buffer's memory at the same time.
Parameters
[in]bufferAn image buffer object
Note
This function does not track sharing between multiple parts of the application. If the application owns multiple references to an image buffer, or shares its buffer memory address between multiple threads, it is the application's responsibility to avoid data races.
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.

◆ ic4_imagebuffer_ref()

struct IC4_IMAGE_BUFFER * ic4_imagebuffer_ref ( struct IC4_IMAGE_BUFFER *  pImageBuffer)

Increases the image buffer's internal reference count by one.

Parameters
[in]pImageBufferAn image buffer
Returns
The pointer passed via pImageBuffer
Remarks
If pImageBuffer is NULL, the function returns NULL. An error value is not set.
See also
ic4_imagebuffer_unref

◆ ic4_imagebuffer_unref()

void ic4_imagebuffer_unref ( struct IC4_IMAGE_BUFFER *  pImageBuffer)

Decreases the image buffer's internal reference count by one.

If the reference count reaches zero, the image buffer is returned to its source to be reused.

Parameters
[in]pImageBufferAn image buffer
Remarks
If pImageBuffer is NULL, the function does nothing. An error value is not set.
See also
ic4_imagebuffer_ref

◆ ic4_imagebuffer_wrap_memory()

bool ic4_imagebuffer_wrap_memory ( struct IC4_IMAGE_BUFFER **  ppBuffer,
void *  data,
size_t  buffer_size,
ptrdiff_t  pitch,
const struct IC4_IMAGE_TYPE *  image_type,
ic4_imagebuffer_memory_release  on_release,
void *  on_release_user_ptr 
)

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
[out]ppBufferPointer to an image buffer handle to receive the new buffer object.
When the buffer is no longer required, release the object reference using ic4_imagebuffer_unref().
[in]dataPointer to a region of memory to be used as image data by the image buffer object
[in]buffer_sizeSize of the region of memory pointed to by data
[in]pitchDifference between memory addresses of two consecutive lines of image data
[in]image_typeType of image to be stored in the image buffer
[in]on_releaseOptional pointer to a 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. ic4_display_display_buffer or ic4_videowriter_add_frame.
[in]on_release_user_ptrUser pointer to be passed when calling on_release.
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_imagetype_tostring()

bool ic4_imagetype_tostring ( const struct IC4_IMAGE_TYPE *  image_type,
char *  buffer,
size_t *  buffer_size 
)

Convert a given image type into a string representation.

Parameters
[out]image_typePointer to a IC4_IMAGE_TYPE value to receive the error code.
[out]bufferPointer to a character array to receive the string.
This parameter can be NULL to find out the required space without allocating an initial array.
[in,out]buffer_sizePointer to a size_t describing the length of the array pointed to by buffer.
The function always writes the actual number of characters required to store the string representation.
Returns
true on success.
If image_type is NULL, the function fails and returns false.
If buffer is not NULL, and *buffer_size is smaller than the required number of bytes to store the string, the function fails and returns false.
Use ic4_get_last_error() to query error information.

◆ ic4_pixelformat_bpp()

size_t ic4_pixelformat_bpp ( enum IC4_PIXEL_FORMAT  pixel_format)

Returns the bits per pixel of a pixel format.

Parameters
[in]pixel_formatpixel format
Returns
The bits required to store one pixel using the given pixel format.
The function returns 0 if the bits per pixel of the pixel format is unknown.

◆ ic4_pixelformat_tostring()

const char * ic4_pixelformat_tostring ( enum IC4_PIXEL_FORMAT  pixel_format)

Returns the name of a pixel format.

Parameters
[in]pixel_formatA pixel format
Returns
A pointer to a null-terminated string containing the name of the pixel format.
The memory pointed to by the return value is valid forever does not need to be released.
If the passed pixel format is unknown, the function returns NULL.