GreRealizeFont

GreRealizeFont requests the presentation driver to realize or delete a font.

This function must be supported by the presentation driver. GreRealizeFont is called during the processing of GpiCreateLogFont to realize the specified logical font. This function call can be handled by bit-map simulation.


 * Simulation support: None. This function is mandatory for all drivers.

Syntax
GreRealizeFont(hdc, cmdCommand, pLogFont, pFont, pInstance, lFunction);

Parameters

 * hdc (HDC) - input
 * Device context handle.


 * cmdCommand (ULONG) - input
 * Command.


 * Valid commands are:


 * RF_DEVICE_FONT (1)
 * The graphics engine asks the presentation driver if it is able to realize a device font for the logical font identified by pLogFont. The action taken by the handling routine depends on the match number of the logical font. The match number is the lMatch parameter in the FONTMETRICS structure of the font specified. See Font Matching for further information.
 * If lMatch is negative, the request is for the device font with the corresponding match number. The handling routine must return the font handle, or 0 if no match was found.
 * If lMatch is 0, the handling routine must search the device fonts for an exact match to pLogFont and return its handle, or 0 if no match was found.
 * If lMatch is a positive value, the handling routine must return 0, as if no font was found.


 * RF_LOAD_ENGINE_FONT (2)
 * The presentation driver is requested to convert an engine font into a device font. The presentation driver must return the font handle, or 0 if it is unable to convert the font.


 * RF_DELETE_FONT (3)
 * The presentation driver is requested to delete a device font. The 32-bit font handle is passed in the pFont parameter.


 * RF_DELETE_ENGINE_FONT (4)
 * Informs the presentation driver that a previously loaded engine font is being deleted. If font caching is not supported, the handling routine performs the action.


 * The font is passed to the presentation driver in the device character bundle during the GreDeviceSetAttribute call. (See Character Attributes.) A bit in the CHARDEFS structure indicates whether this is a pointer to an engine font or the handle to a device font.


 * pLogFont (PFATTRS) - input
 * Pointer to a logical font.


 * The initial value of cmdCommand determines the nature of this parameter:


 * RF_DEVICE_FONT
 * Pointer to a logical font
 * RF_LOAD_ENGINE_FONT
 * Pointer to a logical font
 * RF_DELETE_FONT
 * NULL pointer
 * RF_DELETE_ENGINE_FONT
 * NULL pointer


 * pFont (PULONG) - input
 * Pointer or Handle to font.


 * The initial value of cmdCommand determines the nature of this parameter:
 * RF_DEVICE_FONT
 * NULL pointer
 * RF_LOAD_ENGINE_FONT
 * Pointer to an engine font
 * RF_DELETE_FONT
 * 32-bit device font handle
 * RF_DELETE_ENGINE_FONT
 * Pointer to an engine font.


 * pInstance (PVOID) - input
 * Pointer to instance data.


 * lFunction (ULONG) - input
 * High-order WORD=flags; low-order WORD=NGreRealizeFont.

Return Code

 * rc (ULONG) - returns
 * Return Code.


 * The value returned by this function depends on whether the presentation driver is requested to realize or to delete the font. :When realizing or loading a font, the handling routine must return a 32-bit logical font handle (GPI_ALTERROR), or 0 if the match (or load) was unsuccessful.


 * When deleting a font, the handling routine must return:


 * GPI_OK Successful
 * GPI_ERROR Error


 * Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:


 * PMERR_COORDINATE_OVERFLOW
 * PMERR_DEV_FUNC_NOT_INSTALLED
 * PMERR_HDC_BUSY
 * PMERR_INV_COORD_SPACE
 * PMERR_INV_HDC
 * PMERR_INV_LENGTH_OR_COUNT


 * Refer to the "Error Explanations" section on the Presentation Manager Programming Reference for further explanation.

Remarks
GreRealizeFont is called by the graphics engine to allow the presentation driver to satisfy logical font requests. The example below shows a typical font-matching algorithm for the presentation driver:

 /* If the face name is empty, the application is requesting the default font. Return NO_MATCH.*/

if(Font->szFacename = NULL) {     return(0); }

/* If the match number is positive, an engine font is required. Return NO_MATCH. */

if(Font->lfMatch > 0) {     return(0); }

/* If the match number is negative, a device font is required. The presentation driver should */ /* return the font if it exists; otherwise return NO_MATCH. */

if(Font->lMatch < 0) {    if(font with required lMatch exists) {    /* Check the fsSelection flags and szFacename. If the font is unable to satisfy these    */ /* flags, return NO_MATCH. Otherwise, return the device font handle. */

if((FATTR_FONTUSE_OUTLINE && font not outline)        ||(FATTR_FONTUSE_TRANSFORMABLE && font not outline) ||(szFacename does not match font)) return(0); else return(device_font_handle); }    else {    /* Attempt metrics match (i.e. all metrics including szFaceName, usCodePage, lAveCharWidth */     /* and lMaxBaselineExt). If match exists, return device font handle. Otherwise, return  */ /* NO_MATCH. */

if(metric match exists) {         return(device_font_handle); }      else return(0); }  }

/* The match number is zero, the presentation driver should search for a font with the         */ /* specified metrics, and if an exact match exists, return the device font handle. Otherwise,  */ /* return NO_MATCH. */

if(Font->lMatch = 0) { if(metrics match exists - see above) { /* Check the fsSelection flags. If the font is unable to satisfy these flags, return         */ /* NO_MATCH. Otherwise, return the device font handle. */

if((FATTR_FONTUSE_OUTLINE && font not outline)   ||(FATTR_FONTUSE_TRANSFORMABLE && font not outline)       return(0);    else       return(device_font_handle);  } else   return(0); } 


 * Graphics Engine Simulation
 * 1) The GRE calls GreRealizeFont with cmdCommand equal to RF_DEVICE_FONT if the driver returns 0.
 * 2) The GRE calls again with cmdCommand == RF_LOAD_ENGINE_FONT and the pFont parameter points to a FOCAFONT structure.
 * 3) If the fsDefn field for the font has FM_DEFN_GENERIC and the driver does not report that it is CAPS_RASTER for the GreQueryDeviceCaps entry point, the FOCAFONT will be followed by the character glyphs as documented in the Presentation Manager Programming Reference, Volume 3.
 * 4) Subsequent GreDeviceSetAttributes calls will have the CDEF_GENERIC flag turned off for the font.

Sample Code



 * 1) define INCL_GRE_DEVMISC2
 * 2) include 

HDC       hdc;         /*  Device context handle. */ ULONG     cmdCommand;  /*  Command. */ PFATTRS   pLogFont;    /*  Pointer to a logical font. */ PULONG    pFont;       /*  Pointer or Handle to font. */ PVOID     pInstance;   /*  Pointer to instance data. */ ULONG     lFunction;   /*  High-order WORD=flags; low-order WORD=NGreRealizeFont. */ ULONG     rc;          /*  Return Code. */

rc = GreRealizeFont(hdc, cmdCommand, pLogFont, pFont, pInstance, lFunction); 