int error = RenderText(APTR handle, STRPTR str, int count, int encoding,
                struct hwRenderTextCtrl *pt, struct hwMatrix2D *m, struct
                hwTextLayout *tl, struct hwTagList *tags);

If the plugin hasn't set the HWFONTFLAGS_LAYOUT flag for the font in its LoadFont() implementation, the string passed in str will never contain any line breaks. Handling line breaks is only necessary if your plugin has requested to do its own layouting by setting the HWFONTFLAGS_LAYOUT flag in LoadFont().

The drawing target is passed to RenderText() in the pt parameter. This is a pointer to a struct hwRenderTextCtrl describing a drawing target. struct hwRenderTextCtrl looks like this:

struct hwRenderTextCtrl { int X; [in] int Y; [in] int Width; [in] int Height; [in] APTR RGBData; [in] int RGBModulo; [in] UBYTE *AlphaData; [in] int AlphaModulo; [in] UBYTE *MaskData; [in] int MaskModulo; [in] UBYTE *CLUTData; [in] int CLUTModulo; [in] int PixelFormat; [in] int BytesPerPixel; [in] };

Here is a description of the individual structure members:

X:

This specifies the x-offset you should draw to in the target buffer. An offset of 0 means the leftmost column.

Y:

This specifies the y-offset you should draw to in the target buffer. An offset of 0 means the topmost row.

Width:

This will be set to the target buffer's pixel width, without any row padding.

Height:

This will be set to the target buffer's pixel height.

RGBData:

If the font's color depth has been set to more than 8 in LoadFont(), this member will be set to a pointer to the raw RGB pixel data to draw to. The actual format used by the individual pixels is defined by the PixelFormat member. Please note that even if PixelFormat specifies a 32-bit format with alpha channel, you must never draw any alpha channel pixels to RGBData because Hollywood always stores the alpha channel separately in order to be compatible with 15-bit and 16-bit screenmodes. See Bitmap information for details. You always need to draw the alpha channel pixels to the buffer passed in AlphaData instead.

RGBModulo:

If RGBData is non-NULL, this will contain the number of pixels in a single row in the RGBData buffer. This can be more than returned in Width because Hollywood might choose to allocate some padding bytes for optimized blitting. Note that the value returned in RGBModulo is specified in pixels, not in bytes.

AlphaData:

This member will be set in the following two cases:

1. The font is an RGB color font. In that case you have to draw the color channels to the buffer passed in RGBData and the alpha channel pixels to the buffer passed in AlphaData.
2. The text should be drawn with anti-aliasing. In that case you only have to draw to the buffer passed in AlphaData.

In all other cases AlphaData will be NULL.

AlphaModulo:

If AlphaData is non-NULL, this member will be set to the number of pixels stored in one row of the AlphaData array. This can be more than what is returned in the Width member because Hollywood might use padding bytes for optimized blitting.

MaskData:

You have to draw to this buffer in case the font's color depth has been set to 1 or the font's color depth has been set to 8 and anti-aliasing is turned off. In both cases, MaskData will be set to a buffer you need to draw to. Otherwise it is set to NULL. The data you write to this buffer is interpreted as a monochrome bitmap where set bits indicate visible pixels and cleared bits indicate invisible pixels. The bits are stored from left to right in chunks of one byte, i.e. the most significant bit of the first byte describes the state of the first pixel.

MaskModulo:

If MaskData is non-NULL, this member will be set to the number of bytes that is used for one row of mask data. Note that this value is specified in bytes and often contains some padding.

CLUTData:

You have to draw to this buffer in case the font uses a color palette. Otherwise this member will be NULL. Note that pixels will always be stored as 8 bits per pixel, even if the font palette's depth is less than 8.

CLUTModulo:

If CLUTData is non-NULL, this will be set to the number of pixels per row. This can be more than what is returned in the Width member because Hollywood might use padding bytes for optimized blitting.

PixelFormat:

This member is set to the pixel format used by the pixels written to the RGBData member. See Pixel format information for details.

BytesPerPixel:

This will be set to the number of bytes that are needed to represent one pixel in the RGBData array.

The m parameter may be set to a pointer to a 2D transformation matrix that should be applied to the text before drawing. If can also be NULL which means the identity matrix should be used. Note that m will only ever be set if the font is a vector font and if the plugin has requested to do its own layouting by setting the HWFONTFLAGS_LAYOUT flag in LoadFont().

The tl parameter contains a pointer to a struct hwTextLayout. This structure contains detailed information about the text layout. Most of the structure members are only initialized for fonts that have requested to do their own layouting by setting the HWFONTFLAGS_LAYOUT flag in LoadFont(). The only structure members that are supported for fonts that haven't set HWFONTFLAGS_LAYOUT are CharSpacing and Style but the only style flag that can be set for fonts that haven't set HWFONTFLAGS_LAYOUT is HWFONTSTYLE_ANTIALIAS.

struct hwTextLayout looks like this:

struct hwTextLayout { ULONG Color; [in] ULONG Style; [in] int Align; [in] int WrapWidth; [in] int LineSpacing; [in] int CharSpacing; [in] int Indent; [in] int AdvanceX; [out] int AdvanceY; [out] int *Tabs; [in] int TabCount; [in] };

Here is a description of the individual structure members:

Color:

The desired font color as an RGB value.

Style:

A bit combination of style flags. The following style flags are currently defined:

HWFONTSTYLE_ANTIALIAS:

Use anti-aliasing.

HWFONTSTYLE_BOLD:

Bold text.

HWFONTSTYLE_ITALIC:

Italic text.

HWFONTSTYLE_UNDERLINED:

Underlined text.

Align:

The desired text alignment. This can be one of the following alignment types:

HWTEXTALIGN_LEFT:

Left alignment.

HWTEXTALIGN_RIGHT:

Right alignment.

HWTEXTALIGN_CENTER:

Centered alignment.

HWTEXTALIGN_JUSTIFIED:

Justified alignment.

WrapWidth:

The maximum number of pixels per line. If a word exceeds this number of pixels, it should be moved to the next line. If this is 0, then no wordwrapping should take place.

LineSpacing:

Adjustment pixels between lines. This can be a positive or negative value. A negative value moves lines closer together, whereas a positive value increases the spacing between lines. A value of 0 means no custom line adjustment.

CharSpacing:

Adjustment pixels between characters. This can be a positive or negative value. A negative value moves characters closer together, whereas a positive value increases the spacing between characters. A value of 0 means no custom character adjustment.

Indent:

The indentation in pixels for the very first line of text. If this is greater than 0, text on the very first line should be indented by this number of pixels.

AdvanceX:

This must be set to the number of pixels the cursor should be advanced horizontally after drawing the text.

AdvanceY:

This must be set to the number of pixels the cursor should be advanced vertically after drawing the text.

Tabs:

An integer array containing a number of tab stops. Whenever a tab character is encountered, your text layouter should advance to the next tab stop. The number of tab stops in the Tabs array is indicated by the TabCount member (see below). Note that this can also be NULL.

TabCount:

Number of tab stops in the Tab member (see above).

handle

the font handle allocated by LoadFont()

str

text to draw (this is not null-terminated!)

count

length of the text to draw in bytes

encoding

character encoding of the text (see above)

pt

pointer to a struct hwRenderTextCtrl containing information about the drawing target

m

pointer to a 2D transformation matrix that should be applied before drawing or NULL

tl

pointer to a struct hwTextLayout that contains layout information

tags

tag list containing further options or NULL

error

error code or 0 for success