Class ImageBuffer
Represents an image buffer
Implements
Inherited Members
Namespace: ic4
Assembly: ic4dotnet.dll
Syntax
public class ImageBuffer : HandleObject, IDisposableRemarks
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 FromMemory(IntPtr, ulong, long, ImageType, Action<IntPtr, ulong>).
Programs use image buffers through objects of type ImageBuffer. If the object is disposed, the image buffer is returned to its source for reuse. For example, an image buffer retrieved from PopOutputBuffer() will be re-queued.
Properties
BufferSize
Returns the size of the image buffer.
Declaration
public ulong BufferSize { get; }Property Value
| Type | Description |
|---|---|
| ulong | The size of the image buffer |
Exceptions
| Type | Condition |
|---|---|
| IC4Exception | Check ErrorCode and ToString() for details. |
ImageType
Queries information about the image buffers's image data type.
Declaration
public ImageType ImageType { get; }Property Value
| Type | Description |
|---|---|
| ImageType | A ImageType object describing the type of image that can be stored in the image buffer. |
Exceptions
| Type | Condition |
|---|---|
| IC4Exception | Check ErrorCode and ToString() for details. |
IsWritable
Checks whether an image buffer object is (safely) writable.
Declaration
public bool IsWritable { get; }Property Value
| Type | Description |
|---|---|
| bool |
|
Remarks
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 DisplayBuffer(ImageBuffer) or AddFrame(ImageBuffer) can lead to a buffer becoming shared.
MetaData
Retrieves frame metadata from an image buffer object.
Declaration
public FrameMetaData MetaData { get; }Property Value
| Type | Description |
|---|---|
| FrameMetaData | A FrameMetaData object containing the frame's metadata. |
Exceptions
| Type | Condition |
|---|---|
| IC4Exception | Check ErrorCode and ToString() for details. |
Pitch
Returns the pitch for the image buffer.
Declaration
public long Pitch { get; }Property Value
| Type | Description |
|---|---|
| long | The pitch of the image buffer. The pitch is the distance between the starting memory location of two consecutive lines in bytes. |
Exceptions
| Type | Condition |
|---|---|
| IC4Exception | Check ErrorCode and ToString() for details. |
Ptr
Returns a pointer to the data managed by the image buffer.
Declaration
public IntPtr Ptr { get; }Property Value
| Type | Description |
|---|---|
| IntPtr | A pointer to the image buffer's data. The memory pointed to by the returned pointer is valid as long as the image buffer object exists. |
Exceptions
| Type | Condition |
|---|---|
| IC4Exception | Check ErrorCode and ToString() for details. |
Methods
CopyFrom(ImageBuffer, CopyOptions)
Copies the contents of one image buffer to another image buffer.
Declaration
public void CopyFrom(ImageBuffer other, ImageBuffer.CopyOptions options = CopyOptions.None)Parameters
| Type | Name | Description |
|---|---|---|
| ImageBuffer | other | Source buffer to copy from |
| ImageBuffer.CopyOptions | options | A bitwise combination of ImageBuffer.CopyOptions to customize the copy operation |
Remarks
If the pixel format of the images in other and this is not equal, the image is converted.
For example, if the pixel format of other is BayerRG8 and the pixel
format of this is BGR8, a demosaicing operation creates a color image.
If flags contains SkipImage, the function does not copy the image data.
The function then only copies the chunk data and meta data, and a program-defined algorithm can handle
the image copy operation.
If flags contains SkipChunkData, the function does not copy the chunk data
contained in other. This can be useful if the chunk data is large and not required.
If the width or height of other and this are not equal, the function fails and throws an
IC4Exception with the error code set to ConversionNotSupported.
If there is no algorithm available for the requested conversion, the function fails and throws an IC4Exception with the error code set to ConversionNotSupported.
If this is not writable, the function fails and throws an
InvalidOperationException.
Exceptions
| Type | Condition |
|---|---|
| ArgumentNullException |
|
| InvalidOperationException |
|
| IC4Exception | Check ErrorCode and ToString() for details. |
FromMemory(IntPtr, ulong, long, ImageType, Action<IntPtr, ulong>)
Creates an image buffer object using external memory as storage area for the image data.
Declaration
public static ImageBuffer FromMemory(IntPtr bufferPtr, ulong bufferSize, long pitch, ImageType imageType, Action<IntPtr, ulong> onRelease = null)Parameters
| Type | Name | Description |
|---|---|---|
| IntPtr | bufferPtr | Pointer to a region of memory to be used as image data by the image buffer object |
| ulong | bufferSize | Size of the region of memory pointed to by |
| long | pitch | Difference between memory addresses of two consecutive lines of image data |
| ImageType | imageType | Type of image to be stored in the image buffer |
| Action<IntPtr, ulong> | onRelease | Function to be called when the image buffer is destroyed and the image data will no longer be accessed through it. |
Returns
| Type | Description |
|---|---|
| ImageBuffer | The new image buffer object. |
Remarks
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 image buffer using FromMemory.
- Copy the data from an existing image buffer object into the third-party buffer using CopyFrom(ImageBuffer, CopyOptions).
The program has to make sure that the memory pointed to by bufferPtr stays allocated as long as the image buffer object exists.
Calling Dispose() on an image buffer returned by this function destroys the image buffer object, but does not free the associated memory.
Exceptions
| Type | Condition |
|---|---|
| ArgumentNullException |
|
| IC4Exception | Check ErrorCode and ToString() for details. |
