Herd Software Development
DaVinci Graphics Library
DaVinci Documentation

Leonardo: The TransformDIB function

Transfers the screen contents of a source DIB to a target DIB. Applications can implement up to two callback routines for performing coordinate and color conversions during the copy process.

BOOL FAR PASCAL TransformDIB(
HDIB 	hDibSource, 
HDIB 	hDibDest, 
FNTRANSFORMPOINT	fnPoint, 
FNTRANSFORMCOLOR	fnColor, 
LONG	lParam, 
COLORREF	clBkColor 
);

hDIBSource Handle of a source DIB at 1, 4, 8, 16, 24, 32 or 48 bit color depth.

The handle of the source DIB remains valid after this operation.

hDIBDest Handle of a target DIB at 1, 4, 8, 16, 24, 32 or 48 bit color depth.

Source and target DIBs can be of different resolutions.

fnPoint Application-defined callback function for conversion of coordinates, or NULL if no conversion of coordinates is required.

fnColor Application-defined callback function for color conversion, or NULL if no color conversion is required.

lParam Freely definable supplementary parameter for forwarding to the callback functions, or 0 if no callback functions are required.

clBkColor Color for pixels in the target DIB which do not have a corresponding pixel in the source DIB during coordinate conversion.

Special value: -1 (0xFFFFFFFFL) tells the function to leave target DIB unchanged.

Returns

Returns TRUE if the conversion was successful, FALSE on any error resulting in unsuccessful completion.

How it works

TransformDIB takes the pixel data from the source DIB and copies it pixel by pixel into the destination DIB. Each pixel in the output DIB must be calculated separately using the following process:

• TransformDIB preassigns a target pixel coordinate
  
  
• The fnPoint callback function, if used, assesses the corresponding coordinate in the source DIB
  
  
• The color value of the source DIB's pixel is fetched
  
  
• The fnColor callback function, if used, assesses the desired color in the target DIB for that pixel.
  
  
• The resulting color value is then applied to the appropriate pixel on the destination DIB.

Application of TransformDIB for simple resolution conversion

When callbacks are not used, TransformDIB simply acts as a means of converting DIBs from one color depth to another. If this is all that is required, then create a DIB of the desired color depth with CreateDIB and copy the pixel data using TransformDIB.

TransformDIB supports Win32 16 and 32 bit images as source and/or target DIBs.

Callback functions

TransformDIB allows you to declare either or both of two distinct callback functions as outlined below:

Coordinate conversion, C/C++: BOOL FAR PASCAL _export TransformPoint(UINT msg, LPPOINT lppt, LONG lParam);

PASCAL: Function TransformPoint(msg: Am; lppt: PPoint; LParam: LongInt): Bool; export;

Color conversion, C/C++: BOOL FAR PASCAL _export TransformColor(UINT msg, LPPOINT lppt, LONG lParam, LPRGBQUAD16 lprgbq16);

PASCAL: Function TransformColor(msg: Am; lppt: PPoint; LParam: LongInt; PixelColor: PrgbQuad16): Boolean; export;

TransformPoint and TransformColor are used here as examples; the application can use any names for these functions. All TransformDIB requires is the functions' addresses.

msg Both callback functions are called by TransfromDIB at the beginning and at the end of processing. The msg parameter provides details about the action:

TRFM_INIT Conversion is beginning. Callback routine can initialize private data.

TRFM_LINE Sent before beginning processing of a line. The line number is in lppt->y. Good time to update a progress indicator.

TRFM_PIXEL A pixel's data is about to be processed. lppt specifies the pixel coordinate.

TRFM_EXIT Conversion is complete. Temporary data objects can now be released.

lppt Pointer to a POINT structure with the coordinates of the point (pixel) to be transformed. NULL in the case of TRFM_INIT and TRFM_EXIT.

lParam lParam value transferred in the call of TransformDIB. The application can use this address as a reference value or to store data for use by the callback function.

TransformPoint:

Returns

TRUE: The pixel (TRFM_PIXEL) and/or the line (TRFM_LINE) is transmitted by the source coordinate into the target coordinate.

FALSE: The pixel (TRFM_PIXEL) and/or the line in the target coordinate system (TRFM_LINE) is not affected.

The application pushes the desired source coordinates into the POINT structure addressed by lppt.

TransformColor:

lprgbq16 Pointer to a RGBQUAD16 structure defining the color value as an RGBQUAD16 of the pixel in the source DIB and after the conversion the destination DIB.

Returns TRUE if the pixel was transferred, otherwise FALSE.

Notes regarding the use of callback routines

Callback routines exceeding DLL limits require special handling in applications targetted for Win16 deployment. More information is available in the Windows API documentation for MakeProcInstance. Also see your compiler's documentation regarding smart callbacks or intelligent callbacks.

Be aware that if "smart callbacks" are not used and the callback function's code is not in a DLL, MakeProcInstance handling become rather tricky.

Note that you must either declare your callback functions as exportable (not recommended in Large model programs) or the callback functions must use the export directive. If it helps, the same rules apply to callback functions as would normally apply to window functions.

Examples

1. You can find an example sourcecode of how to use the callback procedures in the DAVDEMO.CPP sample application
   
   
2. It is an unwanted effect of the function RotateDIB that it lasts quite long in the case of big DIBs. However, the function can not be applied to parts of a DIB, therefore, the computer seems to be in the meantime "dead".)
   The documentation includes the source code for RotateDIB so that it can be adapted to situations where this problem needs to be overcome or handled in a certain way.

See also:

RGB (Windows API macro)

COLORREF (and/or OWL/Object Pascal TColorRef type)

RotateDIB source code: ROTATE.C