2.7. tsSetParameter

Syntax

Pascal

procedure tsSetParameteri(ParamName: tsEnum; Param: tsInt);
procedure tsSetParameteriv(ParamName: tsEnum; pParam: ptsInt);

C/C++

void tsSetParameteri(tsEnum ParamName, tsInt Param);
void tsSetParameteriv(tsEnum ParamName, tsInt * pParam);

Description

This function is the main function to control parameters and settings from objects or to control the textoutput.

Params

ParamName

This parameter can have the following values.

Renderer

TS_RENDERER

The renderer is the subsystem which provides the technics to draw some text to the screen. Following values are allowed. There isn't any default value.

[Note] Note

You are only able to change the renderer if no fonts or images has been created. Otherwise the change will fail with TS_INVALID_OPERATION as errorcode (see tsGetError).

TS_RENDERER_OPENGL

This is the main renderer. It provides the main functionallity to draw text with OpenGL. If you print text there are some OpenGL States they will be changed. For an complete list see in the faq section.

TS_RENDERER_NULL

The nullrenderer provides all technics to creates fonts and calculate text dimensions. But it dosn't draws anything. It's only for calculation and other invisble work like precalculations in threads or console applications. With the parameter TS_RENDERER_NULL_SAVE_IMAGES you can control the null renderer to save images or not.

TS_RENDERER_OPENGL_TEXTURE_SIZE

You have the chance to control the dimension of the texture that will be used in the OpenGL renderer.

[Note] Note

This parameter only affects new textures. Existing textures stay unchanged. So it's important to set this parameter early enough.

TS_RENDERER_OPENGL_TEXTURE_SIZE_128

Texturesize will be 128x128

TS_RENDERER_OPENGL_TEXTURE_SIZE_256 (default)

Texturesize will be 256x256. This size normally in enough to store the ansi chars (0-127) of 4 or 5 fonts with sizes around 10 until 14 pixels.

TS_RENDERER_OPENGL_TEXTURE_SIZE_512

Texturesize will be 512x512

TS_RENDERER_OPENGL_TEXTURE_SIZE_1024

Texturesize will be 1024x1024

TS_RENDERER_NULL_SAVE_IMAGES

This parameter controls the generation of the glyphimages.

TS_TRUE (default)

All things works normally. Glyphs and their Images will be created and post processing run as normal. The resulting images are stored internally in the renderer.

TS_FALSE

The generation of the glyph images will be skiped. But the glyphs will be created and the necessary data will be collected.

[Warning] Warning

Make sure if you dosn't create any image no post processor will be applied. Some post processors change some values form chars. So if you are using the null renderer for precalculation or something similar the char values may be different. So it's necessary to save images.

Creator

TS_CREATOR

This parameter controls the type of the creator. The creator is an object that can be attached to an font to give him the ability to create chars. You also can create an font they automatically has an attached creator. At this moment the only way to create an font. Different creators has different reqiurement.

[Note] Note

This parameter hasn't any default value and you must set it at the beginning. For additional informations look in the f.a.q. article "What i have to do to print some text".

TS_CREATOR_SDL

This creator use the SDL_ttf library.

TS_CREATOR_GDI

This creator use the Windows GDI and registers font files inside the font manager of windows.

TS_CREATOR_GDI_FACENAME

Nearly the same creator like TS_CREATOR_GDI but he doesn't register font files. He used the name of the fonts. Thats the typical font usage of windows.

TS_CREATOR_CREATE_CHARS

If the actual bound font an font creator these parameter will control the creation of uncreated chars. As default an creator tries to create chars they not exists.

TS_TRUE (default)

Tries to create chars

TS_FALSE

Don't create chars

TS_GLOBAL_ANTIALIASING

This parameter setting up the default antialiasing for the creator. Its only affects uncreated creator. For details see tsFontCreateCreator.

TS_ANTIALIASING_NONE

The glyph images are getting create without any smoothing.

TS_ANTIALIASING_NORMAL (default)

The glyph images are getting created with smoothing.

TS_GLOBAL_FORMAT

This parameter setting up the default image format for the creator. Its only affects uncreated creator. For the complete list of formats take a look in the Image section. The default format is TS_FORMAT_RGBA8. At this moment the library only supports this.

Font

TS_FONT_ASCENT

The ascent is the space from the baseline up to the top of the line. This value is always positive.

Ascent
TS_FONT_DESCENT

The descent is the space from the baseline to the bottom of the line. This value is always positive.

Descent
TS_FONT_EXTERNAL_LEADING

The external leading is an additional space of each line they will added after ascent and descent. This value comes from the fonts and it's normally really low.

External Leading
TS_FONT_BASELINE_OFFSET

The baseline offset is an value to move the baseline up or down. This is usefull to create formulas or footnotes in texts. This value can be positive or negative. The default is zero.

Baseline offset
TS_FONT_CHAR_SPACING

Charspacing is an aditionall space between chars. The values can be positive or negative. The default is zero.

Char spacing
TS_FONT_LINE_SPACING

Linespacing is an aditionall space between lines. The values can be positive or negative. The default is zero.

Line spacing
TS_FONT_UNDERLINE_POSITION, TS_FONT_UNDERLINE_SIZE

This two values discribes the position and size of the underline. The position is always the top of the line. Relative to the baseline. The size are going to the bottom and they are relative from the top of the underline. In the picture below the values are -8 for the position and 7 for the size.

[Note] Note

For SDL_ttf these values are estimated by me because SDL_ttf dosn't return these values. So it's possible that these line looks wrong. The underline style of SDL_ttf is really useless in my case of usage.

Underline
TS_FONT_STRIKEOUT_POSITION, TS_FONT_STRIKEOUT_SIZE

This two values discribes the position and size of the strikeout line. The position is always the top of the line. Relative to the baseline. The size are going to the bottom and they are relative from the top of the strikeout line. In the picture below the values are 16 for the position and 3 for the size.

[Note] Note

For SDL_ttf these values are estimated by me because SDL_ttf dosn't return these values. So it's possible that these line looks wrong.

Strikeout

Output

TS_ALIGN

The alignment affects the block mode and the single line. You can set one of four horizontal alignments.

TS_ALIGN_LEFT (default)

The text will aligned at the left side.

Align (Left)
TS_ALIGN_RIGHT

The text will aligned at the right side.

Align (Right)
TS_ALIGN_CENTER

The text will align centered.

Align (Center)
TS_ALIGN_BLOCK

The text will aligned in blockmode. This means the left and right side are at the same width. The spaces between the word will be expanded. This mode is only supported in blockmode. In single line mode TS_ALIGN_LEFT will be used instead this.

Align (Block)
TS_VALIGN

For the blockmode you can set one of three vertical alignment to automatically adjust the position of the text. This flags dosn't affect the single line mode.

TS_VALIGN_TOP (default)

Vertikal alignment to top.

TS_VALIGN_CENTER

Vertikal alignment to the center of the block.

TS_VALIGN_BOTTOM

Vertikal alignment to the bottom.

TS_CLIP

If you are in blockmode you can control the clipping of border lines with this parameter. To disable clipping of an block you must pass the TS_BLOCKFLAG_NO_CLIP flag to tsTextBeginBlock. The default value of the clipping is TS_CLIP_COMPLETE.

TS_CLIP_COMPLETE (default)

Clipes lines they are completely outside the defined textblock.

Clip (Complete)
TS_CLIP_BORDER

Clipes al lines they strike the border of the defined textblock.

Clip (Border)
TS_BLOCK_OFFSET_X, TS_BLOCK_OFFSET_Y

This parameters are useful if you want to scroll some text in the block mode. This parameter will change the relative position of the text in the rect of the block mode. The value can be positiv or negativ integers.

TS_SINGLE_LINE

With this you can control the drawing of single lines. The default value is TS_SINGLE_LINE_BASELINE.

TS_SINGLE_LINE_TOP

If this is set the vertical position of the single line text is the upper.

Single Line (Top)
TS_SINGLE_LINE_BASELINE (default)

The vertical position of single line text is the baseline. So it's easy to draw some text with different fonts.

Single line (BaseLine)

Image

TS_IMAGE_LIBRARY

Defines the library which will be used in tsImageLoad to load pictures into the image objects. There is no default value even if TS_IMAGE_LIBRARY_SDL is the only possible value at this moment.

TS_IMAGE_LIBRARY_SDL

Use SDL_image to load the pictures.

TS_IMAGE_RED_MODE, TS_IMAGE_GREEN_MODE, TS_IMAGE_BLUE_MODE, TS_IMAGE_ALPHA_MODE, TS_IMAGE_LUMINANCE_MODE

The image mode defines how pixel operations will be applyed. The functions tsImageFillColor, tsImageFillPattern, tsPostAddFillColor and tsPostAddFillPattern will be effected by this modes. The PostProcessors stores the states at the moment you added it to an font and used the stored state for future operations. For an list of all modes look in the image section.

String

TS_CODEPAGE

There are numerouse codepages supported by this library. For the complete list of codepages take a look in the String section. The defaultcode is TS_CODEPAGE_8859_1.

TS_EMPTY_CP_ENTRY

In some codepages there are some empty entries. This param controls what happens, wenn these entries occours in an text.

TS_EMPTY_CP_ENTRY_IGNORE

Ignores all non existing chars.

TS_EMPTY_CP_ENTRY_USE_DEFAULT (default)

Replaces all non existing chars with the default char

Debugging

TS_DEBUG_DRAW_CHAR_RECTS

Enables the drawing of debug informations. This parameter only effects the drawing of chars. It's not guaranteed that the chars will be draw at the time you have called the tsTextOut functions. So it's may look like that this parameter dosn't work. But in this case it's only an reason of the time.

TS_TRUE

The renderer draws some addinional rects for every char so it's possible to determine the calculated values. If theses values are incorrect the rects dosn't look like the image below. In the image below an additional char spaing was applied.

For each char there will be drawn 3 transparent informations.

  • The whole image will be marked as an light green rect.

  • The rect of the glyph will be drawn with an light red rect. If there are no post processor applyed the both rects has the same size. It should looks like only one rect.

  • The baseline will be displayed with an small blue line.

Debugimage
TS_FALSE (default)

This options dosn't draws additional rects.

Param

The value of this parameter depends on the value in ParamName. For details look above.

pParam

This is the pointer variant of the Param.

Error Codes

TS_NOT_INITIALIZED

If you try to setup the OpenGL renderer but OpenGL wasn't initialized yet. No change to the current renderer will happen.

TS_NO_ACTIVE_CONTEXT

happens if no context was bound.

TS_NO_ACTIVE_RENDERER

The ParamNames TS_RENDERER_OPENGL_TEXTURE_SIZE and TS_RENDERER_NULL_SAVE_IMAGES needs an active renderer. If no renderer was set previously this erreor occours.

TS_NO_ACTIVE_FONT

The ParamNames they begins with TS_FONT_* need an bound font.

TS_INVALID_OPERATION

You have several chances to get this error. But the main reason behind is. It's not allowed to do this operation at the current moment.

  • If you try to change the current renderer and the current allready has some fonts or images. Its not possible to change the renderer if there are still fonts or images. Because they are bound to an renderer.

  • Some ParamNames need an special objecttype to work.

    TS_CREATOR_CREATE_CHARS

    This ParamName needs an FontCreator to work. At this moment the FontCreator is the only fonttype so it wont happen yet.

    TS_RENDERER_OPENGL_TEXTURE_SIZE

    This ParamName is an special setting of the OpenGL renderer so the current renderer needs to be an OpenGL renderer.

    TS_RENDERER_NULL_SAVE_IMAGES

    This ParamName is an special setting of the Null renderer so the current renderer needs to be an Null Renderer.

  • Some ParamNames are restricted in use. That means it's not possible to set some options within an TextBlock. Following ParamNames (TS_RENDERER, all they begins with TS_FONT_*, TS_ALIGN, TS_VALIGN, TS_CLIP, TS_BLOCK_OFFSET_X or TS_BLOCK_OFFSET_Y) are not allowed in block mode.

TS_INVALID_ENUM

If the ParamName is unknown this error occours.

TS_INVALID_VALUE

If you pass nil / NILL or an unknown value as Param you will get this errorcode.