IPFNCBuffer Interface

An IBuffer with GenICam PFNC compliant content. More...

Functions
cvbres_t	CVCBufferGetIncrement (CVBUFFER hBuffer, cvbdim_t Dimension, intptr_t &Increment)
	Gets the offset in bytes to move to the next element in the given Dimension. More...
cvbres_t	CVCBufferGetLength (CVBUFFER hBuffer, cvbdim_t Dimension, cvbint64_t &Length)
	Gets the number of elements (pixels) in the given Dimension. More...
cvbres_t	CVCBufferGetPFNCValue (CVBUFFER hBuffer, cvbuint32_t &PixelFormat)
	Gets the pixel format as defined in the GenICam PFNC. More...
cvbres_t	CVCBufferGetRank (CVBUFFER hBuffer, cvbdim_t &Rank)
	Gets the dimension of the buffer. More...
cvbres_t	CVCGetPFNCValueName (cvbuint32_t PixelFormat, char *Name, size_t &NameLength)
	Gets the readable name (ASCII) of the given PixelFormat. More...
cvbres_t	CVCGetPFNCValueNameW (cvbuint32_t PixelFormat, wchar_t *Name, size_t &NameLength)
	Gets the readable name (Unicode) of the given PixelFormat. More...
cvbbool_t	CVCIsPfncBuffer (CVBUFFER hBuffer)
	Tests whether this a CVB PFNC buffer. More...

Detailed Description

An IBuffer with GenICam PFNC compliant content.

The PFNC describes the meaning and partially the layout of pixel data in the buffer. For the full description see the document at http://www.emva.org/wp-content/uploads/GenICam_PixelFormatValues.pdf

Additionally to the IBuffer interface properties the PixelFormat identifier is provided. For generic handling the Rank of the buffer is given. For example:

2:	standard 2D images
1:	3D point clouds (array of x,y,z points)

And for each Dimension the Length and the Increment to the next element are given. For a 2D image (Rank is two):

0 (CVCD_X):	Length means width in pixels and Increment is the X-increment in bytes
1 (CVCD_Y):	Length means height in pixels and Increment is the Y-increment in bytes

Attention

If you access image data via the IPFNCBuffer interface, you bypass the VPAT. That is only possible if your image both supports the IImageVPA and the IPFNCBuffer interface. With the IPFNCBuffer interface you see the buffer as is (e.g. as delivered by the transport layer). Any rotation, mirroring, etc done via the VPAT is not applied then. If you need that, use the GetLinearAccess function from the CVCUtilities library.

Function Documentation

CVCBufferGetIncrement()

cvbres_t CVCBufferGetIncrement	(	CVBUFFER	hBuffer,
		cvbdim_t	Dimension,
		intptr_t &	Increment
	)

Gets the offset in bytes to move to the next element in the given Dimension.

For a normal image the Increment of Dimension 0 is the X-increment; Dimension 1 refers to the Y-increment respectively.

Attention

Depending on the GenICam PFNC pixel format the Increment may be set to 0. This can either be because the pixel format is packed and the offset to the next pixel has fractions of a byte or the format is unknown.

Also complete pixels are counted here and not their components as in CVB's plane model. Thus an RGB8 image has one R-G-B-tuple as one pixel and the Dimension 0 increment would be 3.

Parameters

[in]	hBuffer	Buffer handle to query.
[in]	Dimension	Dimension to access the increment for.
[out]	Increment	Variable to receive the offset in bytes to the next element in the given Dimension; 0 if unknown or not byte-aligned.

Returns

• #CVC_ERROR (#CVC_E_OK) on success.
• #CVC_ERROR (#CVC_E_WRONGOBJECT) if hBuffer is not an CVBUFFER.
• #CVC_ERROR (#CVC_E_INVALIDINDEX) if Dimension is out of bounds.

CVCBufferGetLength()

cvbres_t CVCBufferGetLength	(	CVBUFFER	hBuffer,
		cvbdim_t	Dimension,
		cvbint64_t &	Length
	)

Gets the number of elements (pixels) in the given Dimension.

For a normal image the Length of Dimension 0 is the width; Dimension 1 refers to the height respectively.

Attention

Here complete pixels are counted and not their components as in CVB's plane model. Thus an RGB8 image has one R-G-B-tuple as one pixel.

Parameters

[in]	hBuffer	Buffer handle to query.
[in]	Dimension	Dimension to access the length for.
[out]	Length	Variable to receive the number of elements in the given Dimension.

Returns

• #CVC_ERROR (#CVC_E_OK) on success.
• #CVC_ERROR (#CVC_E_WRONGOBJECT) if hBuffer is not an CVBUFFER.
• #CVC_ERROR (#CVC_E_INVALIDINDEX) if Dimension is out of bounds.

CVCBufferGetPFNCValue()

cvbres_t CVCBufferGetPFNCValue	(	CVBUFFER	hBuffer,
		cvbuint32_t &	PixelFormat
	)

Gets the pixel format as defined in the GenICam PFNC.

The PFNC describes the meaning and partially the layout of pixel data in the buffer. For the full description see the document at http://www.emva.org/wp-content/uploads/GenICam_PixelFormatValues.pdf

For the actual values see the PFNC.h. You can get a readable name via the CVCGetPFNCValueName(cvbuint32_t, char *, size_t &) or CVCGetPFNCValueNameW(cvbuint32_t, wchar_t *, size_t &) functions.

Parameters

[in]	hBuffer	Buffer handle to query.
[out]	PixelFormat	Variable to receive the PFNC value.

Returns

• #CVC_ERROR (#CVC_E_OK) on success.
• #CVC_ERROR (#CVC_E_WRONGOBJECT) if hBuffer is not an CVBUFFER.

CVCBufferGetRank()

cvbres_t CVCBufferGetRank	(	CVBUFFER	hBuffer,
		cvbdim_t &	Rank
	)

Gets the dimension of the buffer.

For e.g. a normal image the rank would be two (width and height). A sparse point cloud (point list) would have a rank of one.

Parameters

[in]	hBuffer	Buffer handle to query.
[out]	Rank	Variable to receive the number of dimensions in the given hBuffer.

Returns

• #CVC_ERROR (#CVC_E_OK) on success.
• #CVC_ERROR (#CVC_E_WRONGOBJECT) if hBuffer is not an CVBUFFER.

CVCGetPFNCValueName()

cvbres_t CVCGetPFNCValueName	(	cvbuint32_t	PixelFormat,
		char *	Name,
		size_t &	NameLength
	)

Gets the readable name (ASCII) of the given PixelFormat.

Parameters

[in]	PixelFormat	GenICam PFNC pixel format value to translate.
[in]	Name	Buffer to receive the name of the PixelFormat; nullptr to query minimal name length including NUL-termination.
[in,out]	NameLength	Number of elements in Name buffer if Name is not nullptr; variable to receive the minimal number of elements including NUL-termination if Name is nullptr.

Returns

Always #CVC_ERROR (#CVC_E_OK).

CVCGetPFNCValueNameW()

cvbres_t CVCGetPFNCValueNameW	(	cvbuint32_t	PixelFormat,
		wchar_t *	Name,
		size_t &	NameLength
	)

Gets the readable name (Unicode) of the given PixelFormat.

Parameters

[in]	PixelFormat	GenICam PFNC pixel format value to translate.
[in]	Name	Buffer to receive the name of the PixelFormat; nullptr to query minimal name length including NUL-termination.
[in,out]	NameLength	Number of elements in Name buffer if Name is not nullptr; variable to receive the minimal number of elements including NUL-termination if Name is nullptr.

Returns

Always #CVC_ERROR (#CVC_E_OK).

CVCIsPfncBuffer()

cvbbool_t CVCIsPfncBuffer

(

CVBUFFER

hBuffer

)

Tests whether this a CVB PFNC buffer.

A buffer is a congruent chunk of memory. A PFNC buffer additionally gives some hints on its content like pixel format and memory layout.

For the more generic CVB plane approach see CVPLANE related functions.

Parameters

[in]

hBuffer

Buffer handle to check.

Returns

true if hBuffer is a CVB PFNC buffer; false if not.