These functions draw a text string as a simple straight text line. The origin point of the text line is placed at the (x, y) coordinates of the current Output.
The Typesetter provides type (e.g. font, transformation, outline expansion), hinting and positioning attributes to the individual glyphs within the text string, while the two-dimensional transformation matrix tm maps their locations (origin points) to the destination pixel coordinates. Essentially, this mapping represents the projection of points in the native font dependent design space to the final pixel locations.
As with other rendering functions, the current 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 text string when its image is actually rendered.
Parameter | Description |
---|---|
engine |
Handle of the previously created Standard Engine instance. |
x |
X coordinate of the text line's origin point, in pixels. |
y |
Y coordinate of the text line's origin point, in pixels. |
spacing |
Additional spacing between glyphs/characters in the text string, in font units. |
mode |
This parameter specifies the writing direction (horizontal or vertical) and how the function should calculate the position of glyphs/characters. Currently, the following values are supported: Horizontal Writing Mode
Vertical Writing Mode All of the above values are supported in vertical writing mode as well. However, you must combine them with the value 128 (DV_SPACING_VERTICAL) using the OR ("|") operator. For example, (DV_SPACING_VERTICAL | DV_SPACING_KERN_FRAC). This way the function will know the writing direction is vertical. |
tm |
A two-dimensional transformation matrix that maps the locations (origin points) of individual glyphs within the text string to their final pixel coordinates. As mentioned above, this mapping represents the projection of points in the native font dependent design space to the final pixel locations. This parameter can be supplied as DV_NULL. In this case, the function will use a simple scaling matrix which is calculated based on the current type attributes in the Typesetter and is suitable for drawing horizontal text lines. |
glyph_arr |
A string of glyph indices, terminated with DV_ENDOFGLYPHARR. |
chars_arr |
A null-terminated string in UCS4 format. |
glyph_arr_displacement |
An array of glyph displacements (in the direction perpendicular to the writing direction, which depends on the mode parameter), in font units. Each element of this array represents the offset of the corresponding glyph from the baseline. If this value is DV_NULL, all glyph displacement values will be 0. |
glyph_arr_advance |
An array of glyph advancements (in the direction parallel with the writing direction, which depends on the mode parameter), in font units. Each element of this array represents the offset of the corresponding glyph from the previous one. The first element is the offset of the first glyph from the origin. If this value is DV_NULL, the function will calculate glyph advancements automatically, using the default advance width of each glyph. |
start_advance |
Initial advancement value, in pixels. |
The return value represents the advance width of the text string in pixels.
When rendering text, the two-dimensional transformation matrix tm maps the locations (origin points) of individual glyphs within the text string in the native font dependent design space to the final pixel coordinates. This is a very powerful feature which makes it possible to apply various types of transformations to the text lines. As an example, applications can draw horizontal, vertical, rotated or skewed text lines. However, it is important to understand that the two-dimensional transformation matrix tm only controls the placement of the glyph's origin points and has absolutely no impact on the transformation of individual glyphs within the text string. To control the transformation of individual glyphs within the string, call the dtTypesetterSetTypeAttribs or dtTypesetterSetTypeEffects function appropriately.
While the transformation attributes within the DT_TYPE_EFFECTS structure and the transformation matrix tm in this function are completely independent, in many cases you will want them to work in conjunction. For example, when rendering rotated text lines, you will most likely want to rotate both the individual glyphs within the string and apply a rotation matrix to their origin points so that a horizontal line becomes a rotated one. A familiarity with the mathematical properties of two-dimensional transformation matrices is assumed here.
The following example shows a sample text paragraph (at small font size) rendered using different kerning modes.
To view the subtle differences between various kerning modes more easily, each text paragraph is magnified 2 times and shown below separately. Please note, however, that the final output does not only depend on the selected kerning mode, but also the active Positioning and Hinting modes and other Typesetter's parameters such as quality and subpixel precision. Please remember that the Typesetter controls the positioning and hinting of glyphs at the lowest level. You should therefore first set the Typesetter's parameters (by calling dtTypesetterSetHinting, dtTypesetterSetPositioning, dtTypesetterSetQuality, dtTypesetterSetSubpixels and other relevant functions), so they make sense when used in conjunction with the specified kerning mode. For example, it does not make much sense (although it is not illegal) to set mode to DV_SPACING_FRAC if Typesetter's positioning is set to DV_POSITIONING_INTX_INTY. But it does make sense to set Typesetter's positioning to DV_POSITIONING_FRACX_FRACY and use any mode.
In our example, fractional positioning is set to DV_POSITIONING_FRACX_FRACY and hinting is on in both X and Y direction (DV_HINTING_XON_YON). Also, the quality level is set to DV_QUALITY_HINT_FILTER_2. Obviously, our images would look different if hinting or fractional positioning was disabled or if the quality level was set to some other setting.
DV_SPACING_DEVICE and DV_SPACING_KERN_DEVICE
DV_SPACING_DEVICE and DV_SPACING_KERN_DEVICE produce great looking character spacing in a device dependent manner. Since only whole-pixel coordinates are used, all characters look identical regardless of their position.
DV_SPACING_FRAC and DV_SPACING_KERN_FRAC
DV_SPACING_FRAC and DV_SPACING_KERN_FRAC produce nice looking character spacing in a device independent manner. Because in this example fractional positioning is enabled and hinting is on, you will notice that the same characters sometimes look slightly different at different fractional positions (for example, look at the character 'a' in the word 'Saturn' and then in the word 'distant'). If the hinting was off, character spacing would look even better but the overall text appearance would be a little blurry. Regardless of the hinting, this method is very suitable and recommended for a device independent text layout.
DV_SPACING_ROUND_ADD and DV_SPACING_KERN_ROUND_ADD
DV_SPACING_ROUND_ADD and DV_SPACING_KERN_ROUND_ADD can be used in a device dependent text layout but, because of rounding, character spacing is not always ideal. Characters are sometimes either too close or too far apart. Look for example at the word 'planets', 'side', 'this' or 'encircling'. Since pixel coordinates are always rounded, all characters look identical.
DV_SPACING_ADD_ROUND and DV_SPACING_KERN_ADD_ROUND
DV_SPACING_ADD_ROUND and DV_SPACING_KERN_ADD_ROUND can be used in a device independent text layout but, because of rounding, character spacing is not always ideal. Characters are sometimes either too close or too far apart. Look for example at the word 'planets', 'either side' or 'this'. Since pixel coordinates are always rounded, all characters look identical.