Class ImageBuffer

Represents an image buffer

Inheritance

object

HandleObject

ImageBuffer

Implements

IDisposable

Inherited Members

HandleObject.Dispose(bool)

HandleObject.Dispose()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

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.

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.

DuplicateReference()

Duplicates the image buffer reference.

Declaration

public ImageBuffer DuplicateReference()

Returns

Type	Description
ImageBuffer	A copy of this image buffer reference.

Remarks

Both the original image buffer and the return value of this function must be disposed (or garbage collected) before the buffer is reused.

This function can be useful when a function wants to extend the lifetime of an image buffer passed to it.

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.