Description

VuoImageText interface.

Copyright: Copyright © 2012–2020 Kosada Incorporated. This code may be modified and distributed under the terms of the MIT License. For more information, see https://vuo.org/license.

Classes
struct	_VuoImageTextData
	Placement info about text when rendered to an image. More...

Typedefs
typedef struct _VuoImageTextData *	VuoImageTextData
	Placement info about text when rendered to an image. More...

Functions
VuoImageTextData	VuoImageTextData_make ()
	Initialize a new instance of VuoImageTextData. More...

void	VuoImageTextData_free (void *data)
	Free a VuoImageTextData pointer and it's contents. More...

void	VuoImageTextData_convertToVuoCoordinates (VuoImageTextData textData, VuoReal screenWidthInPixels, VuoReal backingScaleFactor)
	Convert VuoImageTextData from pixel coordinates to Vuo coordinates in place. More...

VuoPoint2d	VuoImageTextData_getPositionForLineIndex (VuoImageTextData textData, unsigned int lineIndex)
	Get the origin point of a line of text (bottom left point of first character billboard in line). More...

VuoPoint2d	VuoImageTextData_getPositionForCharIndex (VuoImageTextData textData, unsigned int charIndex, unsigned int *lineIndex)
	Get the starting point for a character index (bottom left corner). More...

int	VuoImageTextData_getNearestCharToPoint (VuoImageTextData textData, VuoPoint2d point)
	Return the character index (0 indexed) nearest to point, where point is relative to the pivot point of a text layer. More...

VuoRectangle *	VuoImageTextData_getRectsForHighlight (VuoImageTextData textData, unsigned int selectionStartIndex, unsigned int selectionLength, unsigned int *lineCount)
	Given a start index and length of selected characters return an array of VuoRectangles encompassing the selection. More...

VuoRectangle	VuoImageTextData_layoutRowAtIndex (VuoImageTextData textData, unsigned int index, unsigned int *charactersRemaining)
	Get a rect that contains a row of text starting at index. More...

unsigned int	VuoImageTextData_getCharIndexForLine (VuoImageTextData textData, unsigned int lineIndex)
	Get the index of the first character at line index. More...

VuoReal	VuoImageText_getLineHeight (VuoFont font, VuoReal screenWidthInPixels, VuoReal backingScaleFactor)
	Get the line height of a font in Vuo coordinates. More...

VuoReal	VuoImageText_getVerticalScale (VuoReal screenWidth, VuoReal screenBackingScaleFactor)
	Get the vertical scaling used for text. More...

VuoImageTextData	VuoImage_getTextImageData (VuoText text, VuoFont font, VuoReal backingScaleFactor, VuoReal verticalScale, VuoReal rotation, bool includeTrailingWhiteSpace)
	Returns a struct containing all information necessary to calculate text and character size and placement when rendered. More...

VuoRectangle	VuoImage_getTextRectangle (VuoText text, VuoFont font, VuoReal backingScaleFactor, VuoReal verticalScale, VuoReal rotation, float wrapWidth, bool includeTrailingWhiteSpace)
	Returns a rectangle (in points) that fully encloses the specified `text` when rendered with the specified `font`. More...

VuoPoint2d	VuoImageText_getTextSize (VuoText text, VuoFont font, VuoPoint2d windowSize, VuoReal backingScaleFactor, bool includeTrailingWhiteSpace)
	Outputs the size in Vuo coordinates of a real-size text layer. More...

VuoImage	VuoImage_makeText (VuoText text, VuoFont font, float backingScaleFactor, float verticalScale, float rotation, float wrapWidth, VuoPoint2d *outCorners)
	Creates an image containing the specified text. More...

Class Documentation

◆ _VuoImageTextData

struct _VuoImageTextData

Class Members
VuoAnchor	billboardAnchor	The anchor point of the billboard used to render this text. This value is unique in that it is not set by VuoImage_getTextImageData, rather, it is assigned by the function responsible for the VuoImage_makeText call.
VuoRectangle	bounds	The bounding box of all text, in pre-transform coordinates.
VuoReal *	charAdvance	The x advance for each character in each line, taking kerning into account.
unsigned int	charCount	The number of characters represented by this data.
VuoReal	height	Bounding rect height, including padding for anti-aliasing.
VuoHorizontalAlignment	horizontalAlignment	The horizontal alignment of this font.
VuoRectangle *	lineBounds	Bounding rect of each line of text.
unsigned int	lineCount	The number of lines text was split into for rendering.
unsigned int *	lineCounts	The number of characters for each line.
VuoReal	lineHeight	The line height for the font.
VuoReal *	lineWidthsExcludingTrailingWhitespace	Same as lineBounds.size.x, but without trailing whitespace or transformation.
VuoReal *	lineXOrigins	Same as lineBounds.origin.x, but without the transformation.
VuoRectangle	transformedBounds	The axis-aligned bounding box of all text, after applying `verticalScale` and `rotation`.
VuoPoint2d	transformedCorners[4]	The text's 4 transformed rectangular corners, in pixels.
VuoReal	width	Bounding rect width, including padding for anti-aliasing. This value can optionally contain the trailing white space (as specified by includeTrailingWhiteSpace).

Typedef Documentation

◆ VuoImageTextData

typedef struct _VuoImageTextData * VuoImageTextData

Placement info about text when rendered to an image.

Changed in Vuo 2.0.0:: Added transformedBounds, transformedCorners, lineWidthsExcludingTrailingWhitespace, lineXOrigins, billboardAnchor.

Function Documentation

◆ VuoImage_getTextImageData()

VuoImageTextData VuoImage_getTextImageData	(	VuoText	text,
		VuoFont	font,
		VuoReal	backingScaleFactor,
		VuoReal	verticalScale,
		VuoReal	rotation,
		bool	includeTrailingWhiteSpace
	)

Returns a struct containing all information necessary to calculate text and character size and placement when rendered.

If text is null or empty, null is returned.

Changed in Vuo 2.0.0:: Added backingScaleFactor, verticalScale, rotation arguments.

Definition at line 413 of file VuoImageText.cc.

◆ VuoImage_getTextRectangle()

VuoRectangle VuoImage_getTextRectangle	(	VuoText	text,
		VuoFont	font,
		VuoReal	backingScaleFactor,
		VuoReal	verticalScale,
		VuoReal	rotation,
		float	wrapWidth,
		bool	includeTrailingWhiteSpace
	)

Returns a rectangle (in points) that fully encloses the specified text when rendered with the specified font.

Depending on the font's design (e.g., if the font is monospace), the rectangle may be larger than the actual glyphs.

Changed in Vuo 2.0.0:: Added backingScaleFactor, verticalScale, rotation, wrapWidth arguments.

Definition at line 392 of file VuoImageText.cc.

◆ VuoImage_makeText()

VuoImage VuoImage_makeText	(	VuoText	text,
		VuoFont	font,
		float	backingScaleFactor,
		float	verticalScale,
		float	rotation,
		float	wrapWidth,
		VuoPoint2d *	outCorners
	)

Creates an image containing the specified text.

If outCorners is not null, this function fills it with the text's 4 transformed bounds in pixels relative to the top-left of the image.

Changed in Vuo 2.0.0:: Added verticalScale, rotation, wrapwidth, outCorners arguments.

Definition at line 739 of file VuoImageText.cc.

◆ VuoImageText_getLineHeight()

VuoReal VuoImageText_getLineHeight	(	VuoFont	font,
		VuoReal	screenWidthInPixels,
		VuoReal	backingScaleFactor
	)

Get the line height of a font in Vuo coordinates.

Useful in cases where no text data is available (ie, you should prefer using textData->lineHeight where available).

Changed in Vuo 2.0.0:: New.

Definition at line 458 of file VuoImageText.cc.

◆ VuoImageText_getTextSize()

VuoPoint2d VuoImageText_getTextSize	(	VuoText	text,
		VuoFont	font,
		VuoPoint2d	windowSize,
		VuoReal	backingScaleFactor,
		bool	includeTrailingWhiteSpace
	)

Outputs the size in Vuo coordinates of a real-size text layer.

windowSize is in points.

Definition at line 436 of file VuoImageText.cc.

◆ VuoImageText_getVerticalScale()

VuoReal VuoImageText_getVerticalScale	(	VuoReal	screenWidth,
		VuoReal	backingScaleFactor
	)

Get the vertical scaling used for text.

Changed in Vuo 2.0.0:: New.

Definition at line 216 of file VuoImageText.cc.

◆ VuoImageTextData_convertToVuoCoordinates()

void VuoImageTextData_convertToVuoCoordinates	(	VuoImageTextData	textData,
		VuoReal	screenWidthInPixels,
		VuoReal	backingScaleFactor
	)

Convert VuoImageTextData from pixel coordinates to Vuo coordinates in place.

Definition at line 484 of file VuoImageText.cc.

◆ VuoImageTextData_free()

void VuoImageTextData_free ( void * data )

Free a VuoImageTextData pointer and it's contents.

Definition at line 101 of file VuoImageText.cc.

◆ VuoImageTextData_getCharIndexForLine()

unsigned int VuoImageTextData_getCharIndexForLine	(	VuoImageTextData	textData,
		unsigned int	lineIndex
	)

Get the index of the first character at line index.

Changed in Vuo 2.0.0:: New.

Definition at line 648 of file VuoImageText.cc.

◆ VuoImageTextData_getNearestCharToPoint()

int VuoImageTextData_getNearestCharToPoint	(	VuoImageTextData	textData,
		VuoPoint2d	point
	)

Return the character index (0 indexed) nearest to point, where point is relative to the pivot point of a text layer.

Definition at line 674 of file VuoImageText.cc.

◆ VuoImageTextData_getPositionForCharIndex()

VuoPoint2d VuoImageTextData_getPositionForCharIndex	(	VuoImageTextData	textData,
		unsigned int	charIndex,
		unsigned int *	lineIndex
	)

Get the starting point for a character index (bottom left corner).

Definition at line 576 of file VuoImageText.cc.

◆ VuoImageTextData_getPositionForLineIndex()

VuoPoint2d VuoImageTextData_getPositionForLineIndex	(	VuoImageTextData	textData,
		unsigned int	lineIndex
	)

Get the origin point of a line of text (bottom left point of first character billboard in line).

Changed in Vuo 2.0.0:: New.

Definition at line 519 of file VuoImageText.cc.

◆ VuoImageTextData_getRectsForHighlight()

VuoRectangle* VuoImageTextData_getRectsForHighlight	(	VuoImageTextData	textData,
		unsigned int	selectionStartIndex,
		unsigned int	selectionLength,
		unsigned int *	lineCount
	)

Given a start index and length of selected characters return an array of VuoRectangles encompassing the selection.

Changed in Vuo 2.0.0:: New.

Definition at line 599 of file VuoImageText.cc.

◆ VuoImageTextData_layoutRowAtIndex()

VuoRectangle VuoImageTextData_layoutRowAtIndex	(	VuoImageTextData	textData,
		unsigned int	index,
		unsigned int *	charactersRemaining
	)

Get a rect that contains a row of text starting at index.

The number of characters from index to line end is stored in length.

Changed in Vuo 2.0.0:: New.

Definition at line 661 of file VuoImageText.cc.

◆ VuoImageTextData_make()

VuoImageTextData VuoImageTextData_make ( )

Initialize a new instance of VuoImageTextData.

Definition at line 87 of file VuoImageText.cc.