VPAT

Virtual Pixel Access Table. More...

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

Typedefs
typedef VPAEntry *	PVPAT
	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
  );
}

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));
}

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

PVPAT

Array of VPAEntry elements returned by GetImageVPA.