
CDTEngineV8
GlyphDoOutput
GlyphDoOutputFrac
CharDoOutput
CharDoOutputFrac
These functions draw a single glyph represented by a Unicode character code (or font dependent glyph index). The glyph is first processed by the Typesetter and then rendered at coordinates (X, Y) of the current Output.
The Typesetter provides type (e.g. font, transformation, outline expansion), hinting and positioning attributes to the glyph to be rendered, while the Output provides the destination surface (which can be either D-Type's Memory Device Context surface or Windows compatible Device Context surface) and style attributes that are applied to the glyph when its image is actually rendered.
In addition, all these functions make an attempt to provide your application with a pointer to the glyph's plain 8-bit grayscale memory bitmap, provided that a) the glyph image is not completely outside the device context's clipping region; b) the glyph image is not too big to fit in the bitmap cache and c) no other bitmap cache restrictions apply (see TypesetterSetSubpixels and TypesetterSetCachePolicy for details). The plain 8-bit grayscale memory bitmap data can be returned as compressed or non-compressed, depending on whether the compression of glyph images in Typesetter's bitmap cache is enabled or disabled (see TypesetterSetCacheCompression for details).
When the device context redirection is disabled in the Output, the functions will not render the glyph to the output surface; instead it will only attempt to provide a pointer to the plain 8-bit grayscale memory bitmap provided that the glyph image is not too big to fit in the bitmap cache and no other bitmap cache restrictions apply.
GlyphDoOutputFrac is identical to GlyphDoOutput except that some of its parameters are 24.8 signed fractional values. Similarly, CharDoOutputFrac is identical to CharDoOutput except that some of its parameters are 24.8 signed fractional values. For more details on fractional units, see the D-Type Units section of this document.
Parameters
Parameter | Description |
char_code
|
Unicode character code of the glyph to be rendered.
|
glyph_index
|
Font dependent index of the glyph to be rendered.
|
x
|
Glyph's X coordinate in pixels.
|
y
|
Glyph's Y coordinate in pixels.
|
reserved
|
Reserved for future use. Must be set to 0.
|
memory_bitmap
|
Either a valid pointer to the DT_BMP structure or DV_NULL. If memory_bitmap is a valid pointer to the DT_BMP structure, then the engine will attempt to return information about the glyph's plain 8-bit grayscale memory bitmap. If successful, the structure's members will hold the following information:
-
memory_bitmap.m — pointer to a memory location in the bitmap cache at which the grayscale memory bitmap data begins. If DV_NULL, the bitmap image is not available. In this case all other member variables will be set to 0.
Important Note 1: This pointer is valid only until the next call to one of D-Type functions that operate on the same Standard Engine instance. This is because subsequent function calls might empty or invalidate the bitmap cache. Therefore, your application should not permanently record the value of the memory_bitmap.m pointer. In addition, your application does not own memory pointed by this pointer and should not attempt to write to it or free it. Instead, your application should either immediately consume (read) the bitmap data or copy it to its own buffer for later use.
Important Note 2: When the bitmap cache compression is enabled, please remember that in this case the bitmap data pointed by memory_bitmap.m is always compressed. You will not be able to properly read this data without first decompressing it. You can use the BitmapDecompress function to decompress compressed grayscale bitmap data. So, in order to properly read the bitmap data, you must know the Typesetter's bitmap cache compression state (see TypesetterSetCacheCompression and TypesetterGetCacheCompression for details).
Important Note 3: Additionally, when the Typesetter's quality level is set to one of the LCD quality levels (DV_QUALITY_LCD_...) or one of the LCD2 quality levels (DV_QUALITY_LCD2_...), the bitmap pointed by memory_bitmap.m may be optimized for LCD screens as follows:
If DV_QUALITY_LCD_..., the bitmap may be LCD-optimized. LCD-optimized bitmaps contain three 8-bit grayscale values per pixel: the first grayscale value is for the R (or B) subpixel intensity, the second one is for the G subpixel intensity and the third one is for the B (or R) subpixel intensity. Such bitmaps contain three times more 8-bit grayscale values than regular bitmaps so it appears as if they were extended in the horizontal direction by a factor of 3. However, their memory_bitmap.w value described below will not be multiplied by 3 as one might expect. In other words, memory_bitmap.w is the same in LCD-optimized bitmaps as in regular bitmaps.
If DV_QUALITY_LCD2_..., the bitmap may be LCD2-optimized. LCD2-optimized bitmaps contain two 8-bit grayscale values per pixel: the first grayscale value is for the G subpixel intensity, the second one is for the combined BR (or RB) subpixel intensity. Such bitmaps contain two times more 8-bit grayscale values than regular bitmaps so it appears as if they were extended in the horizontal direction by a factor of 2. However, their memory_bitmap.w value described below will not be multiplied by 2 as one might expect. In other words, memory_bitmap.w is the same in LCD2-optimized bitmaps as in regular bitmaps.
Note that setting the Typesetter's quality level to one of the LCD quality levels (DV_QUALITY_LCD_...) or one of the LCD2 quality levels (DV_QUALITY_LCD2_...) does not guarantee that the bitmap will be optimized for LCD screens. For example, bitmaps of very small and very large glyphs are never optimized for LCD screens.
memory_bitmap.l — length of the memory buffer in bytes as defined by the DT_BMP structure. Regardless of whether the bitmap cache compression is enabled or disabled, this is always the length of the non-compressed bitmap data (actual length), calculated as follows:
In regular bitmaps (i.e. bitmaps that are neither LCD-optimized nor LCD2-optimized), memory_bitmap.l =
abs(memory_bitmap.w) * abs(memory_bitmap.h)
In LCD-optimized bitmaps, memory_bitmap.l =
3 * abs(memory_bitmap.w) * abs(memory_bitmap.h)
In LCD2-optimized bitmaps, memory_bitmap.l =
2 * abs(memory_bitmap.w) * abs(memory_bitmap.h)
The above equations make it possible to determine whether the bitmap is regular, LCD-optimized or LCD2-optimized.
memory_bitmap.w — width of the bitmap in pixels as defined by the DT_BMP structure. See Important Note 4 below for additional details.
memory_bitmap.h — height of the bitmap in pixels as defined by the DT_BMP structure. See Important Note 4 below for additional details.
memory_bitmap.x — horizontal distance between the bitmap's left edge and glyph's origin in pixels as defined by the DT_BMP structure
memory_bitmap.y — vertical distance between the glyph's origin and bitmap's top edge in pixels as defined by the DT_BMP structure
Important Note 4: memory_bitmap.w and/or memory_bitmap.h can be returned as negative values. A negative value for memory_bitmap.w simply indicates that the glyph's bitmap was hinted and snapped to the pixel grid in the X direction. Similarly, a negative value for memory_bitmap.h indicates that the glyph's bitmap was hinted and snapped to the pixel grid in the Y direction. Regardless of the sign, the absolute value of memory_bitmap.w is always the width of the bitmap in pixels while the absolute value of memory_bitmap.h is always the height of the bitmap in pixels.
If you do not wish to retrieve information about the glyph's plain 8-bit grayscale memory bitmap, simply set memory_bitmap to DV_NULL.
|
Return Value
If successful, the return value is 1. Otherwise, the function returns 0.
Comments
The term plain 8-bit grayscale memory bitmap means a grayscale bitmap without any style effects (e.g. transparency, blur, emboss etc). Special effects are applied only when the bitmap is actually rendered to the Output surface (MDC or HDC) in which the style effect is selected using the OutputSetStyleAttribs function. Plain 8-bit grayscale memory bitmaps are sometimes useful to applications that independently post-process plain 8-bit grayscale data.
