Index

D-Type Standard Engine Structures

In addition to the basic data types, D-Type Standard Engine also defines and utilizes the following structure types:

DT_POINT_FLOAT

This structure type describes a single point using float-point coordinates.

/* Point */ 
typedef struct
{
    DT_FLOAT x, y;

} DT_POINT_FLOAT;

DT_RECT_SWORD

This structure type describers a rectangle whose coordinates are expressed as 16-bit signed integers.

/* D-Type Rectangle (coordinates expressed as 16-bit signed integers) */ 
typedef struct
{
    DT_SWORD xmn, ymn, xmx, ymx;

} DT_RECT_SWORD;

Here, xmn and ymn represent the minimum (x, y) coordinate of the rectangle (or its top left corner) while xmx and ymx represent the maximum (x, y) coordinate of the rectangle (or its bottom right corner).

DT_RECT_SLONG

This structure type describers a rectangle whose coordinates are expressed as 32-bit signed integers.

/* D-Type Rectangle (coordinates expressed as 32-bit signed integers) */ 
typedef struct
{
    DT_SLONG xmn, ymn, xmx, ymx;

} DT_RECT_SLONG;

Here, xmn and ymn represent the minimum (x, y) coordinate of the rectangle (or its top left corner) while xmx and ymx represent the maximum (x, y) coordinate of the rectangle (or its bottom right corner).

DT_ADVANCE

This structure type contains the horizontal and vertical origin, advance width and advance height of a glyph/character in font units.

/* D-Type's glyph/char origins and advances */ 
typedef struct
{
    DT_SWORD x, y; /* horizontal and vertical origin in font units */ 
    DT_UWORD w, h; /* advance width and height in font units */ 

} DT_ADVANCE;

Here, x and y represent the horizontal and vertical origin of the glyph/character while w and h represent its advance width and height.

DT_STYLE_ATTRIBS

This structure type provides style properties that are applied when D-Type renders an output primitive (glyph, character, shape, bitmap) to the output surface. The structure is utilized by the dtOutputSetStyleAttribs and dtOutputGetStyleAttribs functions.

The DT_STYLE_ATTRIBS structure is defined as follows:

/* D-Type Style */ 
typedef struct
{
    DT_UBYTE ep[2];          /* Effect and effect parameter */ 
    DT_UBYTE rgbt[4];        /* Color (Red, Green, Blue) and Transparency */ 
    DT_SWORD reserved;       /* Must be set to 0 */ 
    const DT_UBYTE* palette; /* Either DV_NULL or a valid pointer to a 256-element array */ 

} DT_STYLE_ATTRIBS;

Here, ep represents EffectID and EffectParameter. See Appendix — Style Effects for a list of supported values. The rgbt parameter is simply the intensity of Red (R), Green (G) and Blue (B) and Transparency.

The reserved parameter is reserved for future use and must be set to 0.

The palette parameter must be either DV_NULL or a pointer to an array containing exactly 256 elements. When rendering in true RGB mode, which is highly recommended, set this parameter to DV_NULL. When rendering in indexed color mode, which is an option when the output device is not capable of displaying RGB colors, the R, G, B and T parameters will be ignored and the array pointed by palette will be used instead. In that case, palette must be a valid pointer to an array containing exactly 256 elements. The array must exist at the address pointed by palette as long as the style structure is in use by D-Type Engine (in other words the array can be discarded or freed only after the style has been unloaded from D-Type Engine or replaced by another style). Each element in this array represents a color index of the corresponding gray-level. This provides rudimentary support for rendering in indexed color mode (with limited anti-aliasing and no alpha-blending capabilities). The interpretation of the supplied color indices is up to your application.

DT_STYLE_EFFECTS

This structure type has the same purpose as DT_STYLE_ATTRIBS but is more sophisticated. It allows several style effects to be combined and applied to an output primitive (glyph, character, shape, bitmap) at the same time. It also allows certain style effects to use multiple effect parameters (e.g. Gaussian blur with a different amount of blur in the horizontal and vertical direction). The structure is utilized by the dtOutputSetStyleEffects and dtOutputGetStyleEffects functions.

The DT_STYLE_EFFECTS structure is defined as follows:

/* D-Type Style */ 
typedef struct
{
    DT_SLONG effects_len;     /* Number of effect values */ 
    DT_SLONG effects_arr[64]; /* Array of effect values */ 
    DT_UBYTE rgbt[4];         /* Color (Red, Green, Blue) and Transparency */ 
    const DT_UBYTE* palette;  /* Either DV_NULL or a valid pointer to a 256-element array */ 

} DT_STYLE_EFFECTS;

Here, effects_len is the actual number of elements in the effects_arr array and must not exceed 64. The effects_arr array is an array that contains one or more effect values. The maximum number of values this array can hold is 64. The array begins with the first EffectID, which is followed by the first set of n EffectParameter values. The array continues with the second EffectID, which is followed by the second set of n EffectParameter values. The array continues with the third EffectID, which is followed by the third set of n EffectParameter values. And so on. Once again, the total number of EffectID and EffectParameter values in the array cannot exceed 64.

The number of EffectParameter values in each set (n) depends on the actual EffectID in that set. Some EffectID values have no parameters, while others have 1 or 2 parameters. See Appendix — Style Effects for details.

The rgbt parameter is simply the intensity of Red (R), Green (G) and Blue (B) and Transparency.

The palette parameter must be either DV_NULL or a pointer to an array containing exactly 256 elements. When rendering in true RGB mode, which is highly recommended, set this parameter to DV_NULL. When rendering in indexed color mode, which is an option when the output device is not capable of displaying RGB colors, the R, G, B and T parameters will be ignored and the array pointed by palette will be used instead. In that case, palette must be a valid pointer to an array containing exactly 256 elements. The array must exist at the address pointed by palette as long as the style structure is in use by D-Type Engine (in other words the array can be discarded or freed only after the style has been unloaded from D-Type Engine or replaced by another style). Each element in this array represents a color index of the corresponding gray-level. This provides rudimentary support for rendering in indexed color mode (with limited anti-aliasing and no alpha-blending capabilities). The interpretation of the supplied color indices is up to your application.

DT_LINEDECOR

This structure type contains various line decoration parameters supported by D-Type that can be applied to output primitives (glyphs, characters, and shapes).

/* D-Type Line Decoration */ 
typedef struct
{
    DT_SRAST_L thickness; /* 0=normal, >0=outline, <0=expansion */ 
    DT_SRAST_L segment;   /* Segment len - used for dashing when thickness<>0 */ 
    DT_SRAST_L shift;     /* Must be set to 0 */ 
    DT_UWORD dash_size;   /* Dash size as a percentage of the segment len (0=default, 65535=100%) */ 
    DT_UBYTE flags;       /* Must be set to 0 */ 
    DT_ID_UBYTE scale_id; /* Multiplier ID for thickness, segment and shift (0=multiply by 256, 1=multiply by 100) */ 

} DT_LINEDECOR;

This structure consists of the following components:

DT_TYPE_ATTRIBS

This is a complex structure type that contains information about typographical properties of a glyph or character. The structure is utilized by the dtTypesetterSetTypeAttribs and dtTypesetterGetTypeAttribs functions.

The DT_TYPE_ATTRIBS structure is defined as follows:

/* Type (typographical properties of a glyph or character) */ 
typedef struct
{
    DT_ID_SWORD font_index;  /* Font index from Font Catalog */ 
    DT_SRAST_L thickness;    /* 0=normal, >0=outline, <0=expansion */ 
    DT_SRAST_L segment;      /* Used for dashing when thickness<>0 */ 
    DT_UBYTE reserved;       /* Must be set to 0 */ 
    DT_ID_UBYTE descriptor;  /* 0=transformation via raw params, 1=transformation via 2x2 matrix */ 
    DT_TRANSFORM transform;

} DT_TYPE_ATTRIBS;

This structure consists of the following components:

DT_TYPE_EFFECTS

This is a complex structure type that contains information about typographical properties of a glyph or character. The structure is utilized by the dtTypesetterSetTypeEffects, dtTypesetterSetTypeEffectsTransformed and dtTypesetterGetTypeEffects functions.

This structure type has the same purpose as DT_TYPE_ATTRIBS but is more powerful.

The DT_TYPE_EFFECTS structure is defined as follows:

/* Type (typographical properties of a glyph or character) */ 
typedef struct
{
    DT_ID_SWORD font_index;  /* Font index from Font Catalog */ 
    DT_UBYTE reserved;       /* Must be set to 0 */ 
    DT_ID_UBYTE descriptor;  /* 0=transformation via raw params, 1=transformation via 2x2 matrix */ 
    DT_TRANSFORM transform;
    DT_LINEDECOR linedecor;

} DT_TYPE_EFFECTS;

This structure consists of the following components:

DT_TRANSFORM

This is a union type that describes the transformation to be applied to a glyph or character. Currently, a transformation can be specified in two different ways:

  1. using raw transformation parameters (such as size, skew, rotation)
  2. using a 2x2 transformation matrix

Therefore, this union is defined as follows:

/* Transformation to be applied to a glyph or character */ 
typedef union
{
    DT_TRANSFORM_PARAMS params; /* Transformation via raw params */ 
    DT_TRANSFORM_MATRIX matrix; /* Transformation via 2x2 matrix */ 

} DT_TRANSFORM;

DT_TRANSFORM_PARAMS

If the transformations is specified using raw transformation parameters, the following structure type is used:

/* Transformation specified using raw transformation parameters */ 
typedef struct
{
    DT_SRAST_L size_h, size_v; /* Horizontal and vertical size in pixels (or subpixels) */ 
    DT_SWORD skew_h, skew_v;   /* Horizontal and vertical skew in degrees */ 
    DT_SWORD rotation;         /* Rotation in degrees, must be between 0 and 360 */ 

} DT_TRANSFORM_PARAMS;

This structure consists of the following components:

DT_TRANSFORM_MATRIX

If the transformations is specified using a 2x2 transformation matrix, the following structure type is used:

/* Transformation specified using a 2x2 transformation matrix */ 
typedef struct
{
    DT_SRAST_L tm_00, tm_01; /* m[0][0] and m[0][1] multiplied by 262144 */ 
    DT_SRAST_L tm_10, tm_11; /* m[1][0] and m[1][1] multiplied by 262144 */ 

} DT_TRANSFORM_MATRIX;

Here, the tm_00, tm_01, tm_10 and tm_11 are transformation parameters premultiplied by 262144 and expressed as 32-bit signed integers. In other words, the transformation parameters are 14.18 signed fractional values. Mathematically:

tm_00 = m[0][0] * 262144
tm_01 = m[0][1] * 262144
tm_10 = m[1][0] * 262144
tm_11 = m[1][1] * 262144

As with the DT_TM2X2 data type, the transformation is described by the following formula:

tx = m[0][0] * x + m[0][1] * y
ty = m[1][0] * x + m[1][1] * y

Again, in these equations x and y represent the original point coordinates, m[i][j] represent floating-point transformation parameters, and tx and ty represent the final (transformed) coordinates.

DT_MDC

This structure type contains information about D-Type's memory (off-screen) surfaces.

/* D-Type's memory (off-screen) surface */ 
typedef struct
{
    DT_SRAST_L w, h; /* Surface's dimensions in pixels */ 
    DT_UBYTE* m;     /* Pointer to surface's memory buffer */ 
    DT_SLONG l;      /* Length of the buffer in bytes (defines pitch) */ 

} DT_MDC;

The structure members have the following purpose:

DT_BMP

This structure type contains information about D-Type's 8-bit grayscale memory bitmaps.

/* D-Type's 8-bit grayscale memory bitmap */ 
typedef struct
{
    DT_SRAST_L x, y; /* Bitmap's origin point in pixels */ 
    DT_SRAST_L w, h; /* Bitmap's dimensions in pixels */ 
    DT_UBYTE* m;     /* Pointer to bitmap's memory buffer */ 
    DT_SLONG l;      /* Length of the buffer in bytes */ 

} DT_BMP;

The structure members have the following purpose:

DT_INIT_INFO

This structure type provides additional initialization information to D-Type Engine and receives additional initialization information from D-Type Engine. For details, see the dtEngineIniViaStream function.

/* Additional initialization information */ 
typedef struct
{
    DT_SLONG init_key;    /* Initialization key (0=demo) */ 
    DT_SWORD init_flag;   /* Initialization flag (0=demo) */ 
    DT_SWORD init_status; /* Set by D-Type Engine, provides extended initialization information */ 
    DT_SWORD reserved1;   /* Must be set to 0 */ 
    DT_SWORD reserved2;   /* Must be set to 0 */ 
    void* reserved3;      /* Must be set to DV_NULL */ 
    void* reserved4;      /* Must be set to DV_NULL */ 

} DT_INIT_INFO;

DT_STREAM_DESC

This structure type describes a stream. In D-Type API, a stream is an abstract object that represent a file in some location. Presently, this location can be disk (local or network), memory (RAM) or a local or remote web server (e.g. a Web server on the Internet or local network).

/* Stream structure */ 
typedef struct
{
    DT_ID_UBYTE stream_id;
    DT_UBYTE flags;
    DT_UBYTE reserved1;
    DT_UBYTE reserved2;

    union
    {
        /* File Stream */ 
        const DT_CHAR* file_name; /* used when stream_id=0 or stream_id=1, for reading and writing */ 

        /* Memory Stream */ 
        struct
        {
            const DT_UBYTE* addr;
            DT_SLONG len;

        } mem_r;                  /* used when stream_id=2, for reading */ 

        struct
        {
            DT_UBYTE* addr;
            DT_SLONG len;

        } mem_w;                  /* used when stream_id=2, for writing */ 

        /* URL, FURL and MURL Streams */ 
        const DT_CHAR* url;       /* used when stream_id=3, stream_id=5 or stream_id=6, for reading only */ 

        /* File-Pointer Stream */ 
        FILE* file_ptr;           /* used when stream_id=4, for reading and writing */ 

    } stream_locator;

} DT_STREAM_DESC;

The structure members have the following purpose:

Stream Macros

Rather than setting the members of the DT_STREAM_DESC structure one by one, applications can use the following stream macros to easily create streams that represent files on disk, files in memory (RAM) or files on a local or remote web server:

DT_STREAM_FILE(sd, _file_name)

This macros declares the sd variable as a stream that represent a file on disk. The path of the file is _file_name. This macro has the same effect as the following code:

DT_STREAM_DESC sd;
sd.stream_id=1;
sd.flags=0;
sd.reserved1=0;
sd.reserved2=0;
sd.stream_locator.file_name=_file_name;

DT_STREAM_MEMORY(sd, _mem_addr, _mem_len)

This macros declares the sd variable as a stream that represent a file in memory. The file begins at memory address _mem_addr and its size is _mem_len bytes. This macro has the same effect as the following code:

DT_STREAM_DESC sd;
sd.stream_id=2;
sd.flags=0;
sd.reserved1=0;
sd.reserved2=0;
sd.stream_locator.mem_r.addr=_mem_addr;
sd.stream_locator.mem_r.len=_mem_len;

DT_STREAM_URL(sd, _url)

This macros declares the sd variable as a stream that represent a file on a web server. The URL of the file is _url. This macro has the same effect as the following code:

DT_STREAM_DESC sd;
sd.stream_id=3;
sd.flags=0;
sd.reserved1=0;
sd.reserved2=0;
sd.stream_locator.url=_url;

DT_STREAM_FURL(sd, _url)

This macros declares the sd variable as a stream that represent a file on a web server. The URL of the file is contained within _url (i.e. _url contains the path prefix for the local file to be created relative to the current working directory, followed by the '~' character, followed by the URL of the file). This macro has the same effect as the following code:

DT_STREAM_DESC sd;
sd.stream_id=5;
sd.flags=0;
sd.reserved1=0;
sd.reserved2=0;
sd.stream_locator.url=_url;

DT_STREAM_MURL(sd, _url)

This macros declares the sd variable as a stream that represent a file on a web server. The URL of the file is _url. This macro has the same effect as the following code:

DT_STREAM_DESC sd;
sd.stream_id=6;
sd.flags=0;
sd.reserved1=0;
sd.reserved2=0;
sd.stream_locator.url=_url;

For details on how to use these stream macros, see the How To Use D-Type Streams And Stream Macros section of this manual.

 

Index