Index

C/C++ Functions

dtRasterizerRealloc

DT_SWORD dtRasterizerRealloc(DT_DTENGINE engine, DT_SWORD raster_width, DT_SWORD raster_height, DT_SWORD raster_intersect, DT_ID_SWORD raster_id)

Short Description: Reallocate and/or switch Rasterizer

This function reallocates operating memory required for D-Type Rasterizer to render vectorial shapes. Additionally, this function can be used to change the currently active D-Type Rasterizer.

Parameters

ParameterDescription

engine

Handle of the previously created Standard Engine instance.

raster_width

Maximum width that D-Type Rasterizer will render in a single pass.

raster_height

Maximum height that D-Type Rasterizer will render in a single pass.

raster_intersect

Initial value for maximum number of intersections in a single scan line.

raster_id

One of D-Type Rasterizers. The following values are supported:

  • 0 = Ultra-Fast Grayscale Rasterizer
  • 1 = Perfect Grayscale Rasterizer
  • 2 = Universal Rasterizer — Grayscale
  • 3 = Universal Rasterizer — Black & White

If you do not wish to change the currently active D-Type Rasterizer, set raster_id to -1.

Return Value

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

Comments

In order to render vectorial shapes (e.g. glyphs, characters, user defined shapes), D-Type Rasterizer requires a certain amount of operating memory. This memory is allocated during the initialization of the rasterizer and is approximately calculated using the following formula:

memory = (8 + 4 * raster_intersect) * (raster_width + raster_height) bytes

Vectorial shapes that are larger than raster_width pixels in width or raster_height pixels in height are not rendered in a single pass. Instead, those shapes are rendered using two or multiple pass techniques. In such cases, dtShapeDoOutput, dtGlyphDoOutput and dtCharDoOutput are not able to provide a pointer to the bitmap's 8-bit grayscale data via the DT_BMP structure.

Therefore, applications that expect 8-bit grayscale data via the DT_BMP structure may use the dtRasterizerRealloc function to ensure D-Type Rasterizer can render and return grayscale bitmaps of up to width pixels in width and height pixels in height.

In addition, when rendering complex shapes or characters (e.g. shapes with many horizontal or vertical edges), larger raster_intersect means better performance, since memory reallocations will not be frequent. However, if this value is too big, a large portion of memory will be unused. A good value for raster_intersect is between 8 and 36 for small and medium sizes, and between 2 and 6 for very large sizes.

 

Index