Image Manager (CVCImg.dll) 14.1

Virtual Pixel Access Table. More...

Data Structures

struct  VPAEntry
 Individual entry in the IImageVPA object's PVPAT. More...
 

Typedefs

typedef VPAEntryPVPAT
 Array of VPAEntry elements returned by GetImageVPA. More...
 

Detailed Description

Virtual Pixel Access Table.

Offset table that describes the position in memory of a logical pixel component in an IImageVPA object's plane. It is returned as a PVPAT, an array of VPAEntry elements, by the GetImageVPA function. The offset is calculated based on the returned base pointer.

A function which returns the pointer to a pixel looks like this (returning nullptr on error):

void * GetPixelPointer(IMG Image, cvbval_t PlaneIndex, cvbdim_t X, cvbdim_t Y)
{
if(X < 0 || X >= ImageWidth(Image) || Y < 0 || Y >= ImageHeight(Image))
return nullptr;
intptr_t baseAddress = 0;
PVPAT pVPAT = nullptr;
if(!GetImageVPA(Image, PlaneIndex, reinterpret_cast<void **>(&baseAddress), &pVPAT))
return nullptr;
return reinterpret_cast<void *>
(
baseAddress + pVPAT[Y].YEntry + pVPAT[X].XEntry
);
}
cvbbool_t GetImageVPA(IMG Image, cvbval_t PlaneIndex, void **ppBase, PVPAT *ppVPAT)
Gets the PVPAT and its base pointer to access the image data.
Definition: PseudoCOMExports.cpp:787
cvbdim_t ImageWidth(IMG Image)
Gets the width of the Image.
Definition: PseudoCOMExports.cpp:387
cvbdim_t ImageHeight(IMG Image)
Gets the height of the Image.
Definition: PseudoCOMExports.cpp:413
void * IMG
CVB 2D image handle.
Definition: CVTypes.h:95
Individual entry in the IImageVPA object's PVPAT.
Definition: CVTypes.h:119
intptr_t YEntry
Memory y-offset in bytes (lines).
Definition: CVTypes.h:121
intptr_t XEntry
Memory x-offset in bytes (columns).
Definition: CVTypes.h:120

The use of intptr_t for address calculation and void * for pointer return is intentional. The address calculation is cvbdatatype_t agnostic and therefore is done with byte granularity which is the same as normal integer arithmetic. But it shows nicely that we do not want to dereference this value. To further facilitate this thought we return a void * (with which we cannot do arithmetic). This shows that we only return the pointer to the start of the pixel component.

The cvbdatatype_t defines the data type (and thus size) of the pixel's component. So after we have the address we can cast it to its actual type:

// Mono8 image
cvbuint8_t *pPixel = reinterpret_cast<cvbuint8_t *>(GetPixelPointer(Image, 0, 0, 0);

All this casting at the function's client side is not nice and so we can put it in a template function:

template <typename ConcreteType>
ConcreteType * GetTypedPixelPointer(IMG Image, cvbval_t PlaneIndex, cvbdim_t X, cvbdim_t Y)
{
assert(BytesPerPixel(ImageDatatype(Image, PlaneIndex)) == sizeof(ConcreteType); // added security
return reinterpret_cast<ConcreteType *>(GetPixelPointer(Image, PlaneIndex, X, Y));
}
cvbdatatype_t ImageDatatype(IMG Image, cvbval_t PlaneIndex)
Gets the cvbdatatype_t of the given Image PlaneIndex.
Definition: PseudoCOMExports.cpp:441
cvbval_t BytesPerPixel(cvbdatatype_t Datatype)
Gets how many bytes per pixel (component) are occupied in memory based on the Datatype descriptor.
Definition: PseudoCOMExports.cpp:667

which you can then use like this:

// Mono8 image
cvbuint8_t *pFirstPixel = GetTypedPixelPointer<cvbuint8_t>(Image, 0, 0, 0);

These two functions are very safe and very slow. Normally you would access the image data inside a function and would do all the checking only once.

Note
Pixel access via the VPAT is always done in the pixel coordinate system.
As accessing the pixels via the VPAT always adds one level of indirection (and possibly a cache miss and/or page fault), CVB provides the GetLinearAccess function in the CVCUtilities.dll. See the UtilitiesLibraryReference for additional information.
See also
TCoordinateMap for information on the coordinate systems.

Typedef Documentation

◆ PVPAT

Array of VPAEntry elements returned by GetImageVPA.