IGrabResult Interface#

Interface of the grab result data.

Syntax#

C#

public interface IGrabResult : IDisposable, 
    IImage

VB

Public Interface IGrabResult
    Inherits IDisposable, IImage

The IGrabResult type exposes the following members.

Properties#

	Name	Description
	BlockID	The block ID of the grabbed frame. The format of the value depends on the camera device used.
	BufferUserData	Get the pointer of the buffer context retrieved when calling AllocateBuffer(Int64, Object, IntPtr, Object).
	ChunkData	The collection of attached chunk data.
	Container	Retrieves the container with the data components.
	ErrorCode	The error code generated when an image cannot be grabbed successfully (GrabSucceeded is false).
	ErrorDescription	Description of the error generated when an image cannot be grabbed successfully (GrabSucceeded is false).
	GrabSucceeded	Indicates if an image has been grabbed successfully.
	HasChunkData	Indicates if chunk data is available.
	HasCRC	Indicates if the buffer has a CRC checksum attached. A CRC checksum needs to be activated for the camera device. See the PayloadCRC16 chunk.
	Height	The height of the image in pixels, i.e. the number of image rows. (Inherited from IImage.)
	ID	The ID of the grabbed image.
	ImageNumber	The number of the image.
	IsValid	Indicates if the image is valid. (Inherited from IImage.)
	OffsetX	Horizontal offset from the left side of the sensor to the image ROI.
	OffsetY	Vertical offset from the top of the sensor to the image ROI.
	Orientation	The vertical orientation of the pixel data stored in memory. (Inherited from IImage.)
	PaddingX	The number of data bytes added to the end of each row. (Inherited from IImage.)
	PaddingY	The number of data bytes added to the end of the image data.
	PayloadSize	The current payload size in bytes.
	PayloadTypeValue	The payload type.
	PixelData	The pixel data buffer. The type of the object containing the buffer depends on the class implementing this interface. The pixel data buffer is provided as a byte array if no custom buffer factory is used. With a custom buffer factory the provided type is dependent on its specific implementation. (Inherited from IImage.)
	PixelDataPointer	The pointer to the pixel data buffer. (Inherited from IImage.)
	PixelTypeValue	The pixel type. (Inherited from IImage.)
	SkippedImageCount	The number of images that were skipped before this image was acquired.
	StreamGrabberUserData	The UserData value assigned to the stream grabber object.
	Timestamp	The camera specific tick count.
	Width	The width of the image in pixels, i.e. the number of image columns. (Inherited from IImage.)

Methods#

	Name	Description
	CheckCRC	Indicates if the CRC checksum of the buffer is valid.
	Clone	Clones the grab result for distribution of the grab result data to different modules. All clones must be disposed. The cloned grab result references the same grab result data. No grab result data is copied.

Extension Methods#

	Name	Description
	ComputeStride	Computes the stride of the image in bytes. Returns null if the stride cannot be computed. (Defined by IImageExtensions.)
	Display	Uses the ImageWindow method DisplayImage(Int32, IImage) to display the image. (Defined by IImageExtensions.)

Remarks#

The grab result controls the reuse and the lifetime of the referenced pixel data buffer. If the original and all cloned grab results referencing a pixel data buffer are disposed, the pixel data buffer is freed or reused by the camera stream grabber (depending on the used buffer type). The data and the pixel data buffer are still valid after the original camera object has been disposed.

Caution
If the grab results are never disposed, the grabbing will stop with an input queue underrun.

The grab result interface is derived from IImage. The IImage interface provides the property IsValid. The grab result is considered a valid image if the PixelTypeValue is defined and Width and Height are larger than zero. The PixelData is provided as a byte array if no custom buffer factory is used. With a custom buffer factory the provided type is dependent on its specific implementation.

IGrabResult.CheckCRC Method#

Indicates if the CRC checksum of the buffer is valid.

Syntax#

C#

bool CheckCRC()

VB

Function CheckCRC As Boolean

Return Value#

Type: Boolean
Returns true if the CRC checksum is valid.

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.Clone Method#

Clones the grab result for distribution of the grab result data to different modules. All clones must be disposed. The cloned grab result references the same grab result data. No grab result data is copied.

Syntax#

C#

IGrabResult Clone()

VB

Function Clone As IGrabResult

Return Value#

Type: IGrabResult
Returns a new grab result referencing the same grab result data.

Remarks#

Caution
If the grab results are never disposed, the grabbing will stop with an input queue underrun.

Error Safety:
Can throw exceptions.

IGrabResult.BlockID Property#

The block ID of the grabbed frame. The format of the value depends on the camera device used.

Syntax#

C#

long BlockID { get; }

VB

ReadOnly Property BlockID As Long
    Get

Property Value#

Type: Int64

Remarks#

GigE Camera Devices: The sequence number starts with 1 and wraps at 65535. The value 0 indicates that this feature is not supported by the camera.

USB camera devices: The sequence number starts with 0 and uses the full 64 bit range.

Attention:
A block ID with the value UINT64_MAX indicates that the block ID is invalid and must not be used.

IGrabResult.BufferUserData Property#

Get the pointer of the buffer context retrieved when calling AllocateBuffer(Int64, Object, IntPtr, Object).

Syntax#

C#

Object BufferUserData { get; }

VB

ReadOnly Property BufferUserData As Object
    Get

Property Value#

Type: Object

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.ChunkData Property#

The collection of attached chunk data.

Syntax#

C#

IParameterCollection ChunkData { get; }

VB

ReadOnly Property ChunkData As IParameterCollection
    Get

Property Value#

Type: IParameterCollection

Remarks#

The returned collection can be empty.

Error Safety:
Does not throw exceptions.

IGrabResult.Container Property#

Retrieves the container with the data components.

Syntax#

C#

IDataContainer Container { get; }

VB

ReadOnly Property Container As IDataContainer
    Get

Property Value#

Type: IDataContainer

Remarks#

Any grab result containing an image can create a data container. Some cameras can return grab results consisting of multiple components.

Preconditions: The grab result must be valid.

Error Safety: Does throw exceptions.

IGrabResult.ErrorCode Property#

The error code generated when an image cannot be grabbed successfully (GrabSucceeded is false).

Syntax#

C#

int ErrorCode { get; }

VB

ReadOnly Property ErrorCode As Integer
    Get

Property Value#

Type: Int32

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.ErrorDescription Property#

Description of the error generated when an image cannot be grabbed successfully (GrabSucceeded is false).

Syntax#

C#

string ErrorDescription { get; }

VB

ReadOnly Property ErrorDescription As String
    Get

Property Value#

Type: String

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.GrabSucceeded Property#

Indicates if an image has been grabbed successfully.

Syntax#

C#

bool GrabSucceeded { get; }

VB

ReadOnly Property GrabSucceeded As Boolean
    Get

Property Value#

Type: Boolean

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.HasChunkData Property#

Indicates if chunk data is available.

Syntax#

C#

bool HasChunkData { get; }

VB

ReadOnly Property HasChunkData As Boolean
    Get

Property Value#

Type: Boolean

Remarks#

This is the case if: a) the chunk mode is enabled for the camera device, b) the parameter ChunkNodeMapsEnable of the camera object is set to true (default setting), c) chunk data node maps are supported by the transport layer of the camera device.

Error Safety:
Does not throw exceptions.

IGrabResult.HasCRC Property#

Indicates if the buffer has a CRC checksum attached. A CRC checksum needs to be activated for the camera device. See the PayloadCRC16 chunk.

Syntax#

C#

bool HasCRC { get; }

VB

ReadOnly Property HasCRC As Boolean
    Get

Property Value#

Type: Boolean

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.ID Property#

The ID of the grabbed image.

Syntax#

C#

long ID { get; }

VB

ReadOnly Property ID As Long
    Get

Property Value#

Type: Int64

Remarks#

Always returns a number larger than 0. The counting starts with 1 and is never reset during the lifetime of the Instant Camera object.

Error Safety:
Does not throw exceptions.

IGrabResult.ImageNumber Property#

The number of the image.

Syntax#

C#

long ImageNumber { get; }

VB

ReadOnly Property ImageNumber As Long
    Get

Property Value#

Type: Int64

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.OffsetX Property#

Horizontal offset from the left side of the sensor to the image ROI.

Syntax#

C#

int OffsetX { get; }

VB

ReadOnly Property OffsetX As Integer
    Get

Return Value#

Type: Int32
Horizontal offset from the left side of the sensor to the image ROI. This specifies the position of the image ROI. Only defined if the grab result contains image data.

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.OffsetY Property#

Vertical offset from the top of the sensor to the image ROI.

Syntax#

C#

int OffsetY { get; }

VB

ReadOnly Property OffsetY As Integer
    Get

Return Value#

Type: Int32
Vertical offset from the top of the sensor to the image ROI. This specifies the position of the image ROI. Only defined if the grab result contains image data.

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.PaddingY Property#

The number of data bytes added to the end of the image data.

Syntax#

C#

int PaddingY { get; }

VB

ReadOnly Property PaddingY As Integer
    Get

Property Value#

Type: Int32

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.PayloadSize Property#

The current payload size in bytes.

Syntax#

C#

long PayloadSize { get; }

VB

ReadOnly Property PayloadSize As Long
    Get

Property Value#

Type: Int64

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.PayloadTypeValue Property#

The payload type.

Syntax#

C#

PayloadType PayloadTypeValue { get; }

VB

ReadOnly Property PayloadTypeValue As PayloadType
    Get

Property Value#

Type: PayloadType

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.SkippedImageCount Property#

The number of images that were skipped before this image was acquired.

Syntax#

C#

long SkippedImageCount { get; }

VB

ReadOnly Property SkippedImageCount As Long
    Get

Return Value#

Type: Int64
Always returns a number larger than or equal 0. This number does not include the number of images lost in case of a buffer underrun in the driver.

Remarks#

Error Safety:
Does not throw exceptions.

IGrabResult.StreamGrabberUserData Property#

The UserData value assigned to the stream grabber object.

Syntax#

C#

Object StreamGrabberUserData { get; }

VB

ReadOnly Property StreamGrabberUserData As Object
    Get

Property Value#

Type: Object

Remarks#

The UserData of the stream grabber is attached to the grab result when the grab result is retrieved.

Error Safety:
Does not throw exceptions.

IGrabResult.Timestamp Property#

The camera specific tick count.

Syntax#

C#

long Timestamp { get; }

VB

ReadOnly Property Timestamp As Long
    Get

Property Value#

Type: Int64

Remarks#

The tick count indicates when the image exposure was started. Cameras that do not support this feature return zero. If supported, this can be used to determine which image AOIs were acquired simultaneously.

Error Safety:
Does not throw exceptions.