Index

C/C++ Functions

dtTypesetterSetQuality

DT_SWORD dtTypesetterSetQuality(DT_DTENGINE engine, DT_ID_UBYTE quality, DT_UBYTE flag)

Short Description: Set Typesetter's quality

This function tells the Typesetter which of the available quality levels to use when processing glyphs and characters. At present, there are over twenty predefined quality levels that application developers can choose from.

The default quality level is 0 (DV_QUALITY_MEDIUM) unless D-Type Engine is initialized via an initialization file (i.e. dtype.inf) and the default quality level specified explicitly in this file. Regardless of this, developers can use the dtTypesetterSetQuality function to change the active quality level at any time during the execution of their application.

Parameters

ParameterDescription

engine

Handle of the previously created Standard Engine instance.

quality

The value of this parameter identifies the quality level. The following are the basic quality levels:

  • 0 (DV_QUALITY_MEDIUM) — Medium quality; fast processing. Suitable for animations.

  • 1 (DV_QUALITY_HIGH) — High quality but somewhat slower processing. Suitable for applications that require high quality text output.

  • 2 (DV_QUALITY_VERYHIGH) — Very high quality but somewhat slower processing. Suitable for applications that require very high quality text output.

Note: If D-Type Font Engine is initialized with the Perfect Rasterizer or the Universal Rasterizer — Black & White (for more details see D-Type Rasterizer Overview and the structure of the dtype.inf file in the Initialization Files section of this document), then DV_QUALITY_MEDIUM and DV_QUALITY_HIGH will have the same effect as DV_QUALITY_VERYHIGH. In other words, the quality of these two rasterizers cannot be less than DV_QUALITY_VERYHIGH. This is because both of these rasterizers use an exact formula to calculate the coverage of the outline on each pixel. Only the Ultra-Fast Rasterizer and the Universal Rasterizer — Grayscale allows the applications to change its quality level.

The remaining quality levels use advanced filtering techniques for enhanced text quality and are independent of the active rasterizer:

Note: If you are using the Black & White Rasterizer and wish to ensure that only two levels of gray (black and white) appear in the final output, do not use any of these quality levels.

  • 3 (DV_QUALITY_DISPERSION_FILTER_1) — Enhanced quality with dispersion filter #1. This filter somewhat disperses the energy (i.e. color intensity) of a single pixel to its neighbours. This results in a more balanced color contrast and accurate inter-character positioning but the font hinting effect is diminished. This mode is suitable on display systems where pixels are not very close to each other and/or have limited color dispersion capabilities (such as non-CRT monitors).

  • 4 (DV_QUALITY_DISPERSION_FILTER_2) — Enhanced quality with dispersion filter #2. This filter somewhat disperses the energy (i.e. color intensity) of a single pixel to its neighbours. This results in a more balanced color contrast and very accurate inter-character positioning but the font hinting effect is diminished. This mode is suitable on display systems where pixels are not very close to each other and/or have limited color dispersion capabilities (such as non-CRT monitors). This is one of the highly recommended quality levels.

  • 5 (DV_QUALITY_HINT_FILTER_1) — Enhanced quality with hint filter #1. This filter somewhat disperses the energy (i.e. color intensity) of a single pixel to its neighbours but also preserves the font hinting effect. However, the inter-character positioning is not as accurate as with DV_QUALITY_DISPERSION_FILTER_1 or DV_QUALITY_DISPERSION_FILTER_2.

  • 6 (DV_QUALITY_HINT_FILTER_2) — Enhanced quality with hint filter #2. This filter somewhat disperses the energy (i.e. color intensity) of a single pixel to its neighbours but also preserves the font hinting effect. However, the inter-character positioning is not as accurate as with DV_QUALITY_DISPERSION_FILTER_1 or DV_QUALITY_DISPERSION_FILTER_2. This is one of the highly recommended quality levels.

  • 7 (DV_QUALITY_HINT_FILTER_3) — Enhanced quality with hint filter #3. This filter somewhat disperses the energy (i.e. color intensity) of a single pixel to its neighbours but also preserves the font hinting effect. However, the inter-character positioning is not as accurate as with DV_QUALITY_DISPERSION_FILTER_1 or DV_QUALITY_DISPERSION_FILTER_2.

  • 8 (DV_QUALITY_HINT_FILTER_4) — Enhanced quality with hint filter #4. This filter somewhat disperses the energy (i.e. color intensity) of a single pixel to its neighbours but also preserves the font hinting effect. However, the inter-character positioning is not as accurate as with DV_QUALITY_DISPERSION_FILTER_1 or DV_QUALITY_DISPERSION_FILTER_2.

Although the following quality levels are specifically designed for LCD screens with RGB or BGR subpixel order, they also work very well on standard CRT monitors. In order for these quality levels to function as intended, you must render to D-Type's 24-bpp RGB memory surfaces (identified by format = 24 and subformat = 0 in a call to dtOutputSetAsMDC) or 32-bpp RGB memory surfaces (identified by format = 32 and subformat = 0 or format = 32 and subformat = 1 in a call to dtOutputSetAsMDC). Note that these are new quality levels; they are only available in D-Type Engine 4.0.4.7 and higher.

  • 9 (DV_QUALITY_LCD_RGB_SUB_1) — High quality LCD filter LCD-RGB-SUB-1. Optimized for LCD screens with RGB subpixel order. When this filter is enabled, hinting is performed in the subpixel space. This is one of the highly recommended quality levels on LCD screens with RGB subpixel order.

  • 10 (DV_QUALITY_LCD_RGB_INT_1) — High quality LCD filter LCD-RGB-INT-1. Optimized for LCD screens with RGB subpixel order. When this filter is enabled, hinting is performed in the whole pixel space. This is one of the highly recommended quality levels on LCD screens with RGB subpixel order.

  • 11 (DV_QUALITY_LCD_BGR_SUB_1) — High quality LCD filter LCD-BGR-SUB-1. Same as quality level 9 (DV_QUALITY_LCD_RGB_SUB_1) but optimized for LCD screens with BGR subpixel order. This is one of the highly recommended quality levels on LCD screens with BGR subpixel order.

  • 12 (DV_QUALITY_LCD_BGR_INT_1) — High quality LCD filter LCD-BGR-INT-1. Same as quality level 10 (DV_QUALITY_LCD_RGB_INT_1) but optimized for LCD screens with BGR subpixel order. This is one of the highly recommended quality levels on LCD screens with BGR subpixel order.

  • 13 (DV_QUALITY_LCD_RGB_SUB_2) — High quality LCD filter LCD-RGB-SUB-2. Same as quality level 9 (DV_QUALITY_LCD_RGB_SUB_1) but uses a slightly different filtering approach. Still experimental.

  • 14 (DV_QUALITY_LCD_RGB_INT_2) — High quality LCD filter LCD-RGB-INT-2. Same as quality level 10 (DV_QUALITY_LCD_RGB_INT_1) but uses a slightly different filtering approach. Still experimental.

  • 15 (DV_QUALITY_LCD_BGR_SUB_2) — High quality LCD filter LCD-BGR-SUB-2. Same as quality level 11 (DV_QUALITY_LCD_BGR_SUB_1) but uses a slightly different filtering approach. Still experimental.

  • 16 (DV_QUALITY_LCD_BGR_INT_2) — High quality LCD filter LCD-BGR-INT-2. Same as quality level 12 (DV_QUALITY_LCD_BGR_INT_1) but uses a slightly different filtering approach. Still experimental.

  • 17 (DV_QUALITY_LCD_RGB_SUB_3) — High quality LCD filter LCD-RGB-SUB-3. Same as quality level 9 (DV_QUALITY_LCD_RGB_SUB_1) but uses a slightly different filtering approach. Still experimental.

  • 18 (DV_QUALITY_LCD_RGB_INT_3) — High quality LCD filter LCD-RGB-INT-3. Same as quality level 10 (DV_QUALITY_LCD_RGB_INT_1) but uses a slightly different filtering approach. Still experimental.

  • 19 (DV_QUALITY_LCD_BGR_SUB_3) — High quality LCD filter LCD-BGR-SUB-3. Same as quality level 11 (DV_QUALITY_LCD_BGR_SUB_1) but uses a slightly different filtering approach. Still experimental.

  • 20 (DV_QUALITY_LCD_BGR_INT_3) — High quality LCD filter LCD-BGR-INT-3. Same as quality level 12 (DV_QUALITY_LCD_BGR_INT_1) but uses a slightly different filtering approach. Still experimental.

The remaining quality levels have been introduced in D-Type Engine 4.3.0.1. They are designed for high performance, memory efficient rendering on LCD screens with RGB or BGR subpixel order, but also work very well on standard CRT monitors. In order for these quality levels to function as intended, you must render to D-Type's 24-bpp RGB memory surfaces (identified by format = 24 and subformat = 0 in a call to dtOutputSetAsMDC).

  • 21 (DV_QUALITY_LCD2_RGB_SUB_1) — High quality LCD filter LCD2-RGB-SUB-1. Optimized for LCD screens with RGB subpixel order. When this filter is enabled, hinting is performed in the subpixel space. This is one of the highly recommended quality levels on LCD screens with RGB subpixel order.

  • 22 (DV_QUALITY_LCD2_RGB_INT_1) — High quality LCD filter LCD2-RGB-INT-1. Optimized for LCD screens with RGB subpixel order. When this filter is enabled, hinting is performed in the whole pixel space. This is one of the highly recommended quality levels on LCD screens with RGB subpixel order.

  • 23 (DV_QUALITY_LCD2_BGR_SUB_1) — High quality LCD filter LCD2-BGR-SUB-1. Same as quality level 21 (DV_QUALITY_LCD2_RGB_SUB_1) but optimized for LCD screens with BGR subpixel order. This is one of the highly recommended quality levels on LCD screens with BGR subpixel order.

  • 24 (DV_QUALITY_LCD2_BGR_INT_1) — High quality LCD filter LCD2-BGR-INT-1. Same as quality level 22 (DV_QUALITY_LCD2_RGB_INT_1) but optimized for LCD screens with BGR subpixel order. This is one of the highly recommended quality levels on LCD screens with BGR subpixel order.

  • 25 (DV_QUALITY_LCD2_RGB_SUB_2) — High quality LCD filter LCD2-RGB-SUB-2. Same as quality level 21 (DV_QUALITY_LCD2_RGB_SUB_1) but uses a slightly different filtering approach.

  • 26 (DV_QUALITY_LCD2_RGB_INT_2) — High quality LCD filter LCD2-RGB-INT-2. Same as quality level 22 (DV_QUALITY_LCD2_RGB_INT_1) but uses a slightly different filtering approach.

  • 27 (DV_QUALITY_LCD2_BGR_SUB_2) — High quality LCD filter LCD2-BGR-SUB-2. Same as quality level 23 (DV_QUALITY_LCD2_BGR_SUB_1) but uses a slightly different filtering approach.

  • 28 (DV_QUALITY_LCD2_BGR_INT_2) — High quality LCD filter LCD2-BGR-INT-2. Same as quality level 24 (DV_QUALITY_LCD2_BGR_INT_1) but uses a slightly different filtering approach.

flag

Specifies action with respect to the Typesetter's bitmap cache. Currently supported values are:

  • flag = 0 — Default behavior for this function (bitmap cache will be cleared only if deemed necessary)
  • flag = 1 — Do not clear the bitmap cache
  • flag = 2 — Force clear the bitmap cache

Return Value

If successful, the return value is 1. Otherwise, the function returns 0.

Comments

D-Type Solutions reserves the right to add more quality levels in the future and/or change the ones that are marked as experimental.

Example

The following examples show the effect of various quality levels on the same sample text string. The resulting illustrations are magnified 3 times so that subtle sub-pixel differences can be viewed more easily.

quality = 0 (DV_QUALITY_MEDIUM)
quality = 0 (DV_QUALITY_MEDIUM)
This illustration shows D-Type's lowest quality setting. This setting results in very fast rendering but not so smooth anti-aliasing. Note for example how curved segments in letters 's', 'a', 'p' and 'e' look a little bit jagged.

quality = 1 (DV_QUALITY_HIGH)
quality = 1 (DV_QUALITY_HIGH)
This quality level is similar the previous one except that anti-aliasing is smoother and more accurate. Look at the curved segments in letters 's', 'a', 'p' and 'e' again. Also, note the improved appearance of the letter 'x'.

quality = 2 (DV_QUALITY_VERYHIGH)
quality = 2 (DV_QUALITY_VERYHIGH)
This illustration is very similar the previous one except that anti-aliasing is set to the highest possible level. Most users will not notice a significant improvement in quality however. This is because the difference in quality between DV_QUALITY_HIGH and DV_QUALITY_VERYHIGH is usually very subtle and limited to minute sub-pixel color variations.

quality = 3 (DV_QUALITY_DISPERSION_FILTER_1)
quality = 3 (DV_QUALITY_DISPERSION_FILTER_1)
This illustration shows the effect of the dispersion filter #1. This dispersion filter spreads the energy (i.e. color intensity) of a single pixel to its neighbours. As a consequence, the hinting effect (if enabled by dtTypesetterSetHinting) is partially lost (i.e. the resulting edges in letters are not as sharp as in previous examples) but the overall color balance of the text as well as the inter-character positioning is improved. On some monitors this filter produces more naturally looking text (when viewed from some distance).

quality = 4 (DV_QUALITY_DISPERSION_FILTER_2)
quality = 4 (DV_QUALITY_DISPERSION_FILTER_2)
This illustration shows the effect of the dispersion filter #2. This filter is similar to the previous one, but produces even better looking color balance and inter-character positioning. Note for example the improved appearance of the letter 'm' when compared to the previous example. On most monitors this filter produces very naturally looking text, especially when viewed from some distance.

quality = 5 (DV_QUALITY_HINT_FILTER_1)
quality = 5 (DV_QUALITY_HINT_FILTER_1)
This illustration shows the effect of filter #3. This filter utilizes two techniques: 1) it partially disperses the energy (color intensity) of a single pixel to its neighbours (which then results in a more color balanced output) and 2) preserves the font hinting (grid-fitting) effect. Note that in this example the vertical edges of letters look sharper and have more consistent appearance than in the previous example (e.g. letters 'm', 'l', 't').

quality = 6 (DV_QUALITY_HINT_FILTER_2)
quality = 6 (DV_QUALITY_HINT_FILTER_2)
This filter is very similar to the previous one, but the dispersion factor is reduced by some 8%-10%. This puts more emphasis on the hinting effect. Note, for example, how gray pixels between the vertical edges in letters 'm' and 'p' look slightly softer and lighter.

quality = 7 (DV_QUALITY_HINT_FILTER_3)
quality = 7 (DV_QUALITY_HINT_FILTER_3)
This filter is very similar to the previous one, but the dispersion effect is reduced by another 8%-10% when compared to the previous example. Again, this puts more emphasis on the hinting effect.

quality = 8 (DV_QUALITY_HINT_FILTER_4)
quality = 8 (DV_QUALITY_HINT_FILTER_4)
This filter is very similar to the previous one, but the dispersion effect is reduced by another 8%-10% when compared to the previous example. This puts even more emphasis on the hinting effect. In fact, the resulting image now looks very similar to the one shown under DV_QUALITY_VERYHIGH.

quality = 9 (DV_QUALITY_LCD_RGB_SUB_1)
quality = 9 (DV_QUALITY_LCD_RGB_SUB_1)
This filter is optimized for LCD display systems with RGB supbixel order. It is somewhat similar to the DV_QUALITY_DISPERSION_FILTER_... family of filters, but note how the left and right edges of letters are colored a little bit (red on the left and blue on the right). This coloring effect improves the perceived accuracy of subpixel positioning on LCD screens with RGB supbixel order, which in turn produces very sharp and legible text on those screens.

quality = 10 (DV_QUALITY_LCD_RGB_INT_1)
quality = 10 (DV_QUALITY_LCD_RGB_INT_1)
This filter is optimized for LCD display systems with RGB supbixel order. It is somewhat similar to the DV_QUALITY_HINT_FILTER_... family of filters, but note how the left and right edges of letters are colored a little bit (red on the left and blue on the right). This coloring effect improves the perceived accuracy of subpixel positioning on LCD screens with RGB supbixel order, which in turn produces very sharp and legible text on those screens.

quality = 11 (DV_QUALITY_LCD_BGR_SUB_1)
quality = 11 (DV_QUALITY_LCD_BGR_SUB_1)
This filter is optimized for LCD display systems with BGR supbixel order. It is somewhat similar to the DV_QUALITY_DISPERSION_FILTER_... family of filters, but note how the left and right edges of letters are colored a little bit (blue on the left and red on the right). This coloring effect improves the perceived accuracy of subpixel positioning on LCD screens with BGR supbixel order, which in turn produces very sharp and legible text on those screens.

quality = 12 (DV_QUALITY_LCD_BGR_INT_1)
quality = 12 (DV_QUALITY_LCD_BGR_INT_1)
This filter is optimized for LCD display systems with BGR supbixel order. It is somewhat similar to the DV_QUALITY_HINT_FILTER_... family of filters, but note how the left and right edges of letters are colored a little bit (blue on the left and red on the right). This coloring effect improves the perceived accuracy of subpixel positioning on LCD screens with BGR supbixel order, which in turn produces very sharp and legible text on those screens.

 

Index