Text Renderer. More...

#include <kanzi/core/math/rectangle.hpp>
#include <kanzi/core/cpp/memory.hpp>
#include <kanzi/core.ui/text/kzu_text_layouter.h>
#include "kanzi/core.ui/font/kzu_font_base.h"

Namespaces
	kanzi

Typedefs
typedef shared_ptr< KzuTextFormat >	kanzi::TextFormatSharedPtr
	Text format shared pointer. More...

typedef kzsError(*	kzuTextRendererCreateTextLayouterFunction) (const struct KzcMemoryManager memoryManager, struct KzuFont font, void userData, struct KzuTextLayouter *out_textLayouter)
	Pointer to a function that creates a text layouter. More...

Functions
KANZI_API kzsError	kzuTextRendererCreate (const KzcMemoryManager memoryManager, kanzi::ResourceManager resourceManager, KzuTextRenderer **out_textRenderer)
	Creates a text renderer. More...

KANZI_API kzsError	kzuTextRendererDelete (struct KzuTextRenderer *textRenderer)
	Deletes a text renderer. More...

KANZI_API void	kzuTextRendererClearResources (struct KzuTextRenderer *textRenderer)
	Clears all resources that the text renderer holds. More...

KANZI_API struct KzuTextManager *	kzuTextRendererGetTextManager (const struct KzuTextRenderer *textRenderer)
	Returns the text manager of the text renderer. More...

KANZI_API kanzi::TextFormatSharedPtr	kzuTextRendererCreateTextFormat (const struct KzuTextRenderer textRenderer, struct KzuFont font, kzFloat fontSize, kzFloat width, kzFloat height)
	Creates a text layout. More...

KANZI_API kzFloat	kzuTextFormatGetMaximumWidth (const struct KzuTextFormat *textFormat)
	Gets the maximum width of the text. More...

KANZI_API kzFloat	kzuTextFormatGetMaximumHeight (const struct KzuTextFormat *textFormat)
	Gets the maximum height of the text. More...

KANZI_API KzuFont *	kzuTextFormatGetFont (const struct KzuTextFormat *textFormat)
	Gets the the font of the text. More...

KANZI_API kzFloat	kzuTextFormatGetFontSize (const struct KzuTextFormat *textFormat)
	Gets the font size of the text. More...

KANZI_API void	kzuTextFormatSetTextHorizontalAlignment (struct KzuTextFormat *textFormat, TextConcept::TextHorizontalAlignment alignment)
	Sets the horizontal alignment of the text. More...

KANZI_API TextConcept::TextHorizontalAlignment	kzuTextFormatGetTextHorizontalAlignment (const struct KzuTextFormat *textFormat)
	Gets the horizontal alignment of the text. More...

KANZI_API void	kzuTextFormatSetTextVerticalAlignment (struct KzuTextFormat *textFormat, TextConcept::TextVerticalAlignment alignment)
	Sets the vertical alignment of the text. More...

KANZI_API TextConcept::TextVerticalAlignment	kzuTextFormatGetTextVerticalAlignment (const struct KzuTextFormat *textFormat)
	Gets the vertical alignment of the text. More...

KANZI_API void	kzuTextFormatSetLineSpacing (const struct KzuTextFormat *textFormat, kzFloat lineSpacing)
	Sets the line spacing of the text. More...

KANZI_API kzFloat	kzuTextFormatGetLineSpacing (const struct KzuTextFormat *textFormat)
	Gets the line spacing of the text. More...

KANZI_API void	kzuTextFormatSetCharacterSpacing (const struct KzuTextFormat *textFormat, kzFloat characterSpacing)
	Sets the character spacing of the text. More...

KANZI_API kzFloat	kzuTextFormatGetCharacterSpacing (const struct KzuTextFormat *textFormat)
	Gets the character spacing of the text. More...

KANZI_API void	kzuTextFormatSetFixedCharacterWidth (const struct KzuTextFormat *textFormat, kzFloat fixedCharacterWidth)
	Sets the fixed character width of the text. More...

KANZI_API kzFloat	kzuTextFormatGetFixedCharacterWidth (const struct KzuTextFormat *textFormat)
	Gets the fixed character width of the text. More...

KANZI_API void	kzuTextFormatSetFractionalCharacterWidthEnabled (struct KzuTextFormat *textFormat, bool enabled)
	Enables or disables fractional character width. More...

KANZI_API bool	kzuTextFormatGetFractionalCharacterWidthEnabled (const struct KzuTextFormat *textFormat)
	Gets status of the fractional character width flag. More...

KANZI_API void	kzuTextFormatSetSnapToPixelEnabled (struct KzuTextFormat *textFormat, bool enabled)
	Enables or disables snap to pixel. More...

KANZI_API bool	kzuTextFormatGetSnapToPixelEnabled (const struct KzuTextFormat *textFormat)
	Gets status of the snap to pixel flag. More...

KANZI_API kzsError	kzuTextFormatSetOverflow (const struct KzuTextFormat *textFormat, kzString overflowText)
	Sets the overflow text that is displayed when the text doesn't fit to the layout. More...

KANZI_API kzString	kzuTextFormatGetOverflow (const struct KzuTextFormat *textFormat)
	Gets the overflow text that is displayed when the text doesn't fit to the layout. More...

KANZI_API void	kzuTextFormatSetBidiShapingEnabled (const struct KzuTextFormat *textFormat, kzBool bidiShapingEnabled)
	Sets whether support for complex scripts is enabled. More...

KANZI_API void	kzuTextFormatSetRemoveSideBearingsEnabled (const struct KzuTextFormat *textFormat, bool removeSideBearingsEnabled)
	Sets whether text side bearings removal is enabled. More...

KANZI_API bool	kzuTextFormatGetRemoveSideBearingsEnabled (const struct KzuTextFormat *textFormat)
	Gets status of side bearing removal enabled flag of the text. More...

KANZI_API void	kzuTextFormatSetFontHintingPreference (struct KzuTextFormat *textFormat, kanzi::FontHintingPreference hintingPreference)
	Sets the font hinting preference. More...

KANZI_API kanzi::FontHintingPreference	kzuTextFormatGetFontHintingPreference (const struct KzuTextFormat *textFormat)
	Gets the font hinting preference. More...

KANZI_API kzsError	kzuTextFormatCalculateLayout (struct KzuTextFormat *textFormat, kzString text)
	Calculates the text layout. More...

KANZI_API kzFloat	kzuTextFormatGetWidth (const struct KzuTextFormat *textFormat)
	Gets the width of the area that the text layout actually used. More...

KANZI_API kzFloat	kzuTextFormatGetHeight (const struct KzuTextFormat *textFormat)
	Gets the height of the area that the text layout actually used. More...

KANZI_API const KzuCharacterLayout *	kzuTextFormatGetCharacterLayout (const struct KzuTextFormat *textFormat, kzUint index)
	Gets the layout structure of the given character. More...

KANZI_API KzuTextLayout *	kzuTextFormatGetLayout (const struct KzuTextFormat *textFormat)
	Gets the text layout structure. More...

KANZI_API kzUint	kzuTextFormatGetCharacterCount (const struct KzuTextFormat *textFormat)
	Gets the count of characters. More...

KANZI_API kzBool	kzuTextFormatHasGlyphRun (const struct KzuTextFormat *textFormat)
	Checks if text layout has generated glyph run. More...

KANZI_API kzBool	kzuTextFormatIsTruncated (const struct KzuTextFormat *textFormat)
	Checks if layouted text got truncated, i.e. More...

KANZI_API void	kzuTextFormatPrepareForRendering3D (struct KzuTextFormat *textFormat, kzFloat unitScale, kzFloat offsetX, kzFloat offsetY)
	Prepares a text layout for rendering in 3d space, where x-coordinates increase to the right and y-coordinates increase going upward. More...

KANZI_API void	kzuTextFormatPrepareForRendering3DWithClipping (struct KzuTextFormat textFormat, kzFloat unitScale, const kanzi::Rectangle< float > clippingRectangle, kzFloat offsetX, kzFloat offsetY)
	Prepares a text layout for rendering in a bounded 3d space. More...

KANZI_API void	kzuTextFormatPrepareForRendering2D (struct KzuTextFormat *textFormat, kzFloat unitScale, kzFloat offsetX, kzFloat offsetY)
	Prepares a text layout for rendering in 2d space, where x-coordinates increase to the right and y-coordinates increase going downward. More...

KANZI_API void	kzuTextFormatPrepareForRendering2DWithClipping (struct KzuTextFormat textFormat, kzFloat unitScale, const kanzi::Rectangle< float > clippingArea, kzFloat offsetX, kzFloat offsetY)
	Prepares a text layout for rendering in a bounded 2d space. More...

KANZI_API kzsError	kzuTextFormatCalculateClipping (struct KzuTextFormat textFormat, const kanzi::Rectangle< float > clippingArea)
	Calculates clipped vertex coordinates from the bounding coordinates generated in the preparation function. More...

KANZI_API KzcRectangle	kzuTextFormatGetBoundingRectangle (const struct KzuTextFormat *textFormat)
	Get clipped bounding rectangle for text format. More...

KANZI_API kanzi::TextureSharedPtr	kzuTextRendererGetGlyphTexture (const struct KzuTextRenderer textRenderer, const struct KzuTextFormat textFormat)
	Acquire texture for rendering text format. More...

KANZI_API kzsError	kzuTextRendererDrawTextFormatBrush (const struct KzuTextRenderer textRenderer, kanzi::Renderer3D renderer, const struct KzuTextFormat *textFormat, bool twoPass)
	Renders text format. More...

KANZI_API kzsError	kzuTextRendererDrawTextFormat (const struct KzuTextRenderer textRenderer, kanzi::Renderer3D renderer, const struct KzuTextFormat textFormat, const kanzi::Node node, kanzi::Material &material)
	Renders a text format. More...

KANZI_API kzsError	kzuTextRendererGetBitmapFontSystem (struct KzuTextRenderer textRenderer, struct KzuBitmapFontSystem *out_bitmapFontSystem)
	Gets a bitmap font system. More...

KANZI_API kzsError	kzuTextRendererGetTruetypeSystem (struct KzuTextRenderer textRenderer, struct KzuTruetypeSystem *out_truetypeSystem)
	Gets a TrueType font system. More...

KANZI_API kzsError	kzuTextRendererSetTruetypeSystem (struct KzuTextRenderer textRenderer, struct KzuTruetypeSystem truetypeSystem)
	Sets a TrueType font system, which overrides the default TrueType system. More...

KANZI_API kzsError	kzuTextRendererSetTextLayouterCreator (struct KzuTextRenderer textRenderer, kzuTextRendererCreateTextLayouterFunction createFunction, void userData)
	Sets a creator function for creating text layouters. More...

Detailed Description

Text Renderer.

Typedef Documentation

typedef kzsError(* kzuTextRendererCreateTextLayouterFunction) (const struct KzcMemoryManager *memoryManager, struct KzuFont *font, void *userData, struct KzuTextLayouter **out_textLayouter)

Pointer to a function that creates a text layouter.

Function Documentation

KANZI_API kzsError kzuTextRendererCreate	(	const KzcMemoryManager *	memoryManager,
		kanzi::ResourceManager *	resourceManager,
		KzuTextRenderer **	out_textRenderer
	)

Creates a text renderer.

KANZI_API kzsError kzuTextRendererDelete ( struct KzuTextRenderer * textRenderer )

Deletes a text renderer.

KANZI_API void kzuTextRendererClearResources ( struct KzuTextRenderer * textRenderer )

Clears all resources that the text renderer holds.

KANZI_API struct KzuTextManager* kzuTextRendererGetTextManager ( const struct KzuTextRenderer * textRenderer )

Returns the text manager of the text renderer.

KANZI_API kanzi::TextFormatSharedPtr kzuTextRendererCreateTextFormat	(	const struct KzuTextRenderer *	textRenderer,
		struct KzuFont *	font,
		kzFloat	fontSize,
		kzFloat	width,
		kzFloat	height
	)

Creates a text layout.

The text layout specifies the maximum area which can be used to layout text. The width and height are specified in pixels and they can be KZS_INFINITY for an unbounded area.

KANZI_API kzFloat kzuTextFormatGetMaximumWidth ( const struct KzuTextFormat * textFormat )

Gets the maximum width of the text.

KANZI_API kzFloat kzuTextFormatGetMaximumHeight ( const struct KzuTextFormat * textFormat )

Gets the maximum height of the text.

KANZI_API KzuFont* kzuTextFormatGetFont ( const struct KzuTextFormat * textFormat )

Gets the the font of the text.

KANZI_API kzFloat kzuTextFormatGetFontSize ( const struct KzuTextFormat * textFormat )

Gets the font size of the text.

KANZI_API void kzuTextFormatSetTextHorizontalAlignment	(	struct KzuTextFormat *	textFormat,
		TextConcept::TextHorizontalAlignment	alignment
	)

Sets the horizontal alignment of the text.

KANZI_API TextConcept::TextHorizontalAlignment kzuTextFormatGetTextHorizontalAlignment ( const struct KzuTextFormat * textFormat )

Gets the horizontal alignment of the text.

KANZI_API void kzuTextFormatSetTextVerticalAlignment	(	struct KzuTextFormat *	textFormat,
		TextConcept::TextVerticalAlignment	alignment
	)

Sets the vertical alignment of the text.

KANZI_API TextConcept::TextVerticalAlignment kzuTextFormatGetTextVerticalAlignment ( const struct KzuTextFormat * textFormat )

Gets the vertical alignment of the text.

KANZI_API void kzuTextFormatSetLineSpacing	(	const struct KzuTextFormat *	textFormat,
		kzFloat	lineSpacing
	)

Sets the line spacing of the text.

The line spacing is specified in multiples of the normal line height which is specified by the font.

KANZI_API kzFloat kzuTextFormatGetLineSpacing ( const struct KzuTextFormat * textFormat )

Gets the line spacing of the text.

KANZI_API void kzuTextFormatSetCharacterSpacing	(	const struct KzuTextFormat *	textFormat,
		kzFloat	characterSpacing
	)

Sets the character spacing of the text.

The character spacing is specified in multiples of the normal character spacing which is specified by the font.

KANZI_API kzFloat kzuTextFormatGetCharacterSpacing ( const struct KzuTextFormat * textFormat )

Gets the character spacing of the text.

KANZI_API void kzuTextFormatSetFixedCharacterWidth	(	const struct KzuTextFormat *	textFormat,
		kzFloat	fixedCharacterWidth
	)

Sets the fixed character width of the text.

The character width is specified in pixels.

KANZI_API kzFloat kzuTextFormatGetFixedCharacterWidth ( const struct KzuTextFormat * textFormat )

Gets the fixed character width of the text.

KANZI_API void kzuTextFormatSetFractionalCharacterWidthEnabled	(	struct KzuTextFormat *	textFormat,
		bool	enabled
	)

Enables or disables fractional character width.

KANZI_API bool kzuTextFormatGetFractionalCharacterWidthEnabled ( const struct KzuTextFormat * textFormat )

Gets status of the fractional character width flag.

KANZI_API void kzuTextFormatSetSnapToPixelEnabled	(	struct KzuTextFormat *	textFormat,
		bool	enabled
	)

Enables or disables snap to pixel.

KANZI_API bool kzuTextFormatGetSnapToPixelEnabled ( const struct KzuTextFormat * textFormat )

Gets status of the snap to pixel flag.

KANZI_API kzsError kzuTextFormatSetOverflow	(	const struct KzuTextFormat *	textFormat,
		kzString	overflowText
	)

Sets the overflow text that is displayed when the text doesn't fit to the layout.

KANZI_API kzString kzuTextFormatGetOverflow ( const struct KzuTextFormat * textFormat )

Gets the overflow text that is displayed when the text doesn't fit to the layout.

KANZI_API void kzuTextFormatSetBidiShapingEnabled	(	const struct KzuTextFormat *	textFormat,
		kzBool	bidiShapingEnabled
	)

Sets whether support for complex scripts is enabled.

This includes support for bi-directional text and languages that require ligatures.

KANZI_API void kzuTextFormatSetRemoveSideBearingsEnabled	(	const struct KzuTextFormat *	textFormat,
		bool	removeSideBearingsEnabled
	)

Sets whether text side bearings removal is enabled.

If enabled removes side bearings for each line separately making text start right next to the sides.

KANZI_API bool kzuTextFormatGetRemoveSideBearingsEnabled ( const struct KzuTextFormat * textFormat )

Gets status of side bearing removal enabled flag of the text.

KANZI_API void kzuTextFormatSetFontHintingPreference	(	struct KzuTextFormat *	textFormat,
		kanzi::FontHintingPreference	hintingPreference
	)

Sets the font hinting preference.

KANZI_API kanzi::FontHintingPreference kzuTextFormatGetFontHintingPreference ( const struct KzuTextFormat * textFormat )

Gets the font hinting preference.

KANZI_API kzsError kzuTextFormatCalculateLayout	(	struct KzuTextFormat *	textFormat,
		kzString	text
	)

Calculates the text layout.

KANZI_API kzFloat kzuTextFormatGetWidth ( const struct KzuTextFormat * textFormat )

Gets the width of the area that the text layout actually used.

The width is returned in pixels. The text layout must be calculated before calling this function.

KANZI_API kzFloat kzuTextFormatGetHeight ( const struct KzuTextFormat * textFormat )

Gets the height of the area that the text layout actually used.

The height is returned in pixels. The text layout must be calculated before calling this function.

KANZI_API const KzuCharacterLayout* kzuTextFormatGetCharacterLayout	(	const struct KzuTextFormat *	textFormat,
		kzUint	index
	)

Gets the layout structure of the given character.

The text layout must be calculated before calling this function.

KANZI_API KzuTextLayout* kzuTextFormatGetLayout ( const struct KzuTextFormat * textFormat )

Gets the text layout structure.

The text layout must be calculated before calling this function.

KANZI_API kzUint kzuTextFormatGetCharacterCount ( const struct KzuTextFormat * textFormat )

Gets the count of characters.

The text layout must be calculated before calling this function.

KANZI_API kzBool kzuTextFormatHasGlyphRun ( const struct KzuTextFormat * textFormat )

Checks if text layout has generated glyph run.

KANZI_API kzBool kzuTextFormatIsTruncated ( const struct KzuTextFormat * textFormat )

Checks if layouted text got truncated, i.e.

it did not fit. The text layout must be calculated before calling this function.

KANZI_API void kzuTextFormatPrepareForRendering3D	(	struct KzuTextFormat *	textFormat,
		kzFloat	unitScale,
		kzFloat	offsetX,
		kzFloat	offsetY
	)

Prepares a text layout for rendering in 3d space, where x-coordinates increase to the right and y-coordinates increase going upward.

The z-coordinate of the text is always 0.0f. The pixel size of the text font is multiplied by the scale to get the size of the text in the 3d space. The text offsets given in 3d space units are used to calculate proper horizontal aligning. They should be set to half of the width and height of the whole text format.

KANZI_API void kzuTextFormatPrepareForRendering3DWithClipping	(	struct KzuTextFormat *	textFormat,
		kzFloat	unitScale,
		const kanzi::Rectangle< float > *	clippingRectangle,
		kzFloat	offsetX,
		kzFloat	offsetY
	)

Prepares a text layout for rendering in a bounded 3d space.

Generates unclipped vertex positions and bounding box coordinates for the clipping function to use.

KANZI_API void kzuTextFormatPrepareForRendering2D	(	struct KzuTextFormat *	textFormat,
		kzFloat	unitScale,
		kzFloat	offsetX,
		kzFloat	offsetY
	)

Prepares a text layout for rendering in 2d space, where x-coordinates increase to the right and y-coordinates increase going downward.

The pixel size of the text font is multiplied by the scale to get the size of the text in the 2d space.

KANZI_API void kzuTextFormatPrepareForRendering2DWithClipping	(	struct KzuTextFormat *	textFormat,
		kzFloat	unitScale,
		const kanzi::Rectangle< float > *	clippingArea,
		kzFloat	offsetX,
		kzFloat	offsetY
	)

Prepares a text layout for rendering in a bounded 2d space.

Generates unclipped vertex positions and bounding box coordinates for the clipping function to use.

KANZI_API kzsError kzuTextFormatCalculateClipping	(	struct KzuTextFormat *	textFormat,
		const kanzi::Rectangle< float > *	clippingArea
	)

Calculates clipped vertex coordinates from the bounding coordinates generated in the preparation function.

Characters that are outside the bounded area are clipped completely, and characters that are on the border of area are clipped so that only part of the character is visible.

KANZI_API KzcRectangle kzuTextFormatGetBoundingRectangle ( const struct KzuTextFormat * textFormat )

Get clipped bounding rectangle for text format.

Parameters

textFormat Text format to query.

Returns: Rectangle.

KANZI_API kanzi::TextureSharedPtr kzuTextRendererGetGlyphTexture	(	const struct KzuTextRenderer *	textRenderer,
		const struct KzuTextFormat *	textFormat
	)

Acquire texture for rendering text format.

Parameters

textRenderer	Text renderer to use.
textFormat	Text format to render.

Returns: Glyph texture.

KANZI_API kzsError kzuTextRendererDrawTextFormatBrush	(	const struct KzuTextRenderer *	textRenderer,
		kanzi::Renderer3D *	renderer,
		const struct KzuTextFormat *	textFormat,
		bool	twoPass
	)

Renders text format.

Used for rendering with a brush or material renderer. Shader and glyph texture are assumed to be already bound by brush or material renderer.

If two-pass rendering is enabled, all color information is first written with depth write disabled and then in the second pass depth information is written with color write disabled. This is slower than rendering in one pass, but needed for correct rendering result when glyph bounds are overlapping.

Parameters

textRenderer	Text renderer to use.
renderer	Renderer to use.
textFormat	Text format to draw.

KANZI_API kzsError kzuTextRendererDrawTextFormat	(	const struct KzuTextRenderer *	textRenderer,
		kanzi::Renderer3D *	renderer,
		const struct KzuTextFormat *	textFormat,
		const kanzi::Node *	node,
		kanzi::Material &	material
	)

Renders a text format.

The text format must be calculated and prepared for rendering before calling this function. If the material is KZ_NULL, uses the default font material.

KANZI_API kzsError kzuTextRendererGetBitmapFontSystem	(	struct KzuTextRenderer *	textRenderer,
		struct KzuBitmapFontSystem **	out_bitmapFontSystem
	)

Gets a bitmap font system.

It is created and deleted automatically if necessary.

KANZI_API kzsError kzuTextRendererGetTruetypeSystem	(	struct KzuTextRenderer *	textRenderer,
		struct KzuTruetypeSystem **	out_truetypeSystem
	)

Gets a TrueType font system.

It is created and deleted automatically if necessary.

KANZI_API kzsError kzuTextRendererSetTruetypeSystem	(	struct KzuTextRenderer *	textRenderer,
		struct KzuTruetypeSystem *	truetypeSystem
	)

Sets a TrueType font system, which overrides the default TrueType system.

KANZI_API kzsError kzuTextRendererSetTextLayouterCreator	(	struct KzuTextRenderer *	textRenderer,
		kzuTextRendererCreateTextLayouterFunction	createFunction,
		void *	userData
	)

Sets a creator function for creating text layouters.

Pass KZ_NULL as the function to reset to the default implementation.

Namespaces

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation