Class ImageBuffer

Represents an image buffer

Inheritance

ImageBuffer

Implements

Namespace: ic4
Assembly: ic4dotnet.dll
Syntax
public class ImageBuffer : HandleObject, IDisposable
Remarks

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

true, if the image buffer not shared with any part of the library, and is therefore safely writable, otherwise false.

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

other is null

InvalidOperationException

this is not writable. Check IsWritable for details.

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 data

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

imageType is null

IC4Exception

Check ErrorCode and ToString() for details.

Implements

Extension Methods