Herd Software Development
DaVinci Graphics Library
DaVinci Documentation

Accessing DIBs at the pixel level using RWxxxx functions

The RWxxxx function group in Leonardo provides you with an easy way to read, write and work pixel-by-pixel with DIB data. Leonardo is particularly well-suited to, and recommended for, working with 48 bit and CMYK image formats.

Design

Opening a DIB for read/write operations

In order to process DIB data at the pixel level at high speeds, RWOpenDIB caches supplementary information about the DIB. This requires that a HDIBRW cache handle must first be assigned from Leonardo as follows:

HDIB	hDIB;
HDIBRW	hRW = RWOpenDIB(hDIB);

Read/write of individual pixels

The calling application can now address the pixels in the DIB. The following functions are available for access to DIBs at the pixel level:

RWGetPixel and RWSetPixel works in virtually the same fashion as the GetPixel API function.
RWGetPixelRGB16 and RWSetPixelRGB16 are provided to allow access to pixels in DIB data at a resolution of 16 bits per color channel.
RWGetPixelIndex and RWSetPixelIndex provide access to pixel data in the original data format of the DIB. Prior to use, a PIXELINDEXUNION structure must be filled with the biBitCount and biPlanes of the original DIB opened with RWOpenDIB. For these functions do not need to convert binary pixel data to RGBValues they are faster, particulary when processing DIBs at 4 or 8 bit per pixel. Applications should give preference to these functions if they only need to copy pixels without consdering the RGB-Meaning of the pixels.
```
COLORREF     cr;
RGBQUAD16    rgbq16;

// Example: Invert a Pixel
cr = RWGetPixel(hRW, x, y);
cr = RGB( 255 - GetRValue (cr),
          255 - GetGValue (cr),
          255 - GetBValue (cr) );
RWSetPixel(hRW, x, y, cr);

// The same with RGBQ16
RWGetPixelRGB16 (hRW, x, y, &rgbq16);
rgbq.rgb16Red   = 65535 - rgbq.rgb16Red;
rgbq.rgb16Green = 65535 - rgbq.rgb16Green;
rgbq.rgb16Blue  = 65535 - rgbq.rgb16Blue;
RWSetPixelRGB16(hRW, x, y, &rgbq16);
```

Read/write of entire DIB lines

Even faster access to individual pixels can be achieved by working with a whole DIB line, or by working with parts of the line as array of RGBQUAD16 structures. For this purpose the application needs to allocate an array of RGBQUAD16 structures.

#define BLOCK_SIZE	256

RGBQUAD16            argbq[BLOCK_SIZE];
BITMAPINFOHEADER     bmi;
UINT                 x, i;

DIBInfo(hDib, &bmi, sizeof(bmi));

for (x=0; x<bmi.biWidth; ++x)
{
   RWGetLineRGB16(hRW, x, y, BLOCK_SIZE, argbq);

   for (i=0; i<BLOCK_SIZE; ++i)
   {
      argbq[i].rgbq16Red   = 65535 - argbq[i].rgbq16Red
      argbq[i].rgbq16Green = 65535 - argbq[i].rgbq16Green
      argbq[i].rgbq16Blue  = 65535 - argbq[i].rgbq16Blue
   }

   RWSetLineRGB16(hRW, x, y, BLOCK_SIZE, argbq);
}

Closing the DIB

When no further access to the DIB is required, the calling application must free the DIB access handle obtained by the call to RWOpenDIB by calling the function RWClose

Performance considerations

Routines in the RWxxxx function group are optimized for speed, but they can't achieve the same performance as direct memory access by the application.

Especially slow functions are setting of pixels by RGB values if the DIB has a color palette (biBitCount=4 or biBitCount=8 or biBitCount=1 with colors not beeing black and white). In this case, the function RWSetPixelRGB16 first has to determine the best color palette index for the RGB value, a very time-consuming process. Once the index value for a RGB-Color has been determined, it is cached in a 256 KByte memory block.

For two especially important cases Leonardo contains optimized code to speed up processing:

A quadratic 6*6*6 RGB color palette with 17 supplementary gray levels like they are created by DitherTo8 and CreateDIB.
A gray shade stairs with rgb[PaletteIndex] = PaletteIndex as it is generated by GrayDIB.