playout.h File Reference

C API for paragraph layout. More...

#include "unicode/ubidi.h"
#include "layout/LETypes.h"
#include "plruns.h"

Go to the source code of this file.

Typedefs

typedef void pl_paragraph
 The opaque type for a paragraph layout.
typedef void pl_line
 The opaque type for a line in a paragraph layout.
typedef void pl_visualRun
 The opaque type for a visual run in a line.

Functions

pl_paragraphpl_create (const LEUnicode chars[], le_int32 count, const pl_fontRuns *fontRuns, const pl_valueRuns *levelRuns, const pl_valueRuns *scriptRuns, const pl_localeRuns *localeRuns, UBiDiLevel paragraphLevel, le_bool vertical, LEErrorCode *status)
 Construct a ParagraphLayout object for a styled paragraph.
void pl_close (pl_paragraph *paragraph)
 Close the given paragraph layout object.
le_bool pl_isComplex (const LEUnicode chars[], le_int32 count)
 Examine the given text and determine if it contains characters in any script which requires complex processing to be rendered correctly.
UBiDiLevel pl_getParagraphLevel (pl_paragraph *paragraph)
 Return the resolved paragraph level.
UBiDiDirection pl_getTextDirection (pl_paragraph *paragraph)
 Return the directionality of the text in the paragraph.
le_int32 pl_getAscent (const pl_paragraph *paragraph)
 Get the max ascent value for all the fonts in the paragraph.
le_int32 pl_getDescent (const pl_paragraph *paragraph)
 Return the max descent value for all the fonts in the paragraph.
le_int32 pl_getLeading (const pl_paragraph *paragraph)
 Return the max leading value for all the fonts in the paragraph.
void pl_reflow (pl_paragraph *paragraph)
 Reset line breaking to start from the beginning of the paragraph.
pl_linepl_nextLine (pl_paragraph *paragraph, float width)
 Return a pl_line object which represents next line in the paragraph.
void pl_closeLine (pl_line *line)
 Close the given line object.
le_int32 pl_countLineRuns (const pl_line *line)
 Count the number of visual runs in the line.
le_int32 pl_getLineAscent (const pl_line *line)
 Get the ascent of the line.
le_int32 pl_getLineDescent (const pl_line *line)
 Get the descent of the line.
le_int32 pl_getLineLeading (const pl_line *line)
 Get the leading of the line.
le_int32 pl_getLineWidth (const pl_line *line)
 Get the width of the line.
const pl_visualRunpl_getLineVisualRun (const pl_line *line, le_int32 runIndex)
 Get a ParagraphLayout::VisualRun object for a given visual run in the line.
const le_font * pl_getVisualRunFont (const pl_visualRun *run)
 Get the le_font object which represents the font of the visual run.
UBiDiDirection pl_getVisualRunDirection (const pl_visualRun *run)
 Get the direction of the visual run.
le_int32 pl_getVisualRunGlyphCount (const pl_visualRun *run)
 Get the number of glyphs in the visual run.
const LEGlyphIDpl_getVisualRunGlyphs (const pl_visualRun *run)
 Get the glyphs in the visual run.
const float * pl_getVisualRunPositions (const pl_visualRun *run)
 Get the (x, y) positions of the glyphs in the visual run.
const le_int32pl_getVisualRunGlyphToCharMap (const pl_visualRun *run)
 Get the glyph-to-character map for this visual run.
le_int32 pl_getVisualRunAscent (const pl_visualRun *run)
 A convenience method which returns the ascent value for the font associated with this run.
le_int32 pl_getVisualRunDescent (const pl_visualRun *run)
 A convenience method which returns the descent value for the font associated with this run.
le_int32 pl_getVisualRunLeading (const pl_visualRun *run)
 A convenience method which returns the leading value for the font associated with this run.

Detailed Description

C API for paragraph layout.

This is a technology preview. The API may change significantly.

Definition in file playout.h.


Typedef Documentation

typedef void pl_line

The opaque type for a line in a paragraph layout.

Internal:
Do not use. This API is for internal use only.

Definition at line 41 of file playout.h.

typedef void pl_paragraph

The opaque type for a paragraph layout.

Internal:
Do not use. This API is for internal use only.

Definition at line 34 of file playout.h.

typedef void pl_visualRun

The opaque type for a visual run in a line.

Internal:
Do not use. This API is for internal use only.

Definition at line 48 of file playout.h.


Function Documentation

void pl_close ( pl_paragraph paragraph  ) 

Close the given paragraph layout object.

Parameters:
paragraph the pl_paragraph object to be closed. Once this routine returns the object can no longer be referenced
Internal:
Do not use. This API is for internal use only.
void pl_closeLine ( pl_line line  ) 

Close the given line object.

Line objects are created by pl_nextLine but it is the client's responsibility to close them by calling this routine.

Parameters:
line the pl_line object to close.
Internal:
Do not use. This API is for internal use only.
le_int32 pl_countLineRuns ( const pl_line line  ) 

Count the number of visual runs in the line.

Parameters:
line the pl_line object.
Returns:
the number of visual runs.
Internal:
Do not use. This API is for internal use only.
pl_paragraph* pl_create ( const LEUnicode  chars[],
le_int32  count,
const pl_fontRuns fontRuns,
const pl_valueRuns levelRuns,
const pl_valueRuns scriptRuns,
const pl_localeRuns localeRuns,
UBiDiLevel  paragraphLevel,
le_bool  vertical,
LEErrorCode status 
)

Construct a ParagraphLayout object for a styled paragraph.

The paragraph is specified as runs of text all in the same font. An LEFontInstance object and a limit offset are specified for each font run. The limit offset is the offset of the character immediately after the font run.

Clients can optionally specify directional runs and / or script runs. If these aren't specified they will be computed.

If any errors are encountered during construction, status will be set, and the object will be set to be empty.

Parameters:
chars is an array of the characters in the paragraph
count is the number of characters in the paragraph.
fontRuns a pointer to a pl_fontRuns object representing the font runs.
levelRuns is a pointer to a pl_valueRuns object representing the directional levels. If this pointer in NULL the levels will be determined by running the Unicde Bidi algorithm.
scriptRuns is a pointer to a pl_valueRuns object representing script runs. If this pointer in NULL the script runs will be determined using the Unicode code points.
localeRuns is a pointer to a pl_localeRuns object representing locale runs. The Locale objects are used to determind the language of the text. If this pointer is NULL the default locale will be used for all of the text.
paragraphLevel is the directionality of the paragraph, as in the UBiDi object.
vertical is TRUE if the paragraph should be set vertically.
status will be set to any error code encountered during construction.
Returns:
a pointer to the newly created pl_paragraph object. The object will remain valid until pl_close is called.
See also:
ubidi.h
longine.h
plruns.h
Internal:
Do not use. This API is for internal use only.
le_int32 pl_getAscent ( const pl_paragraph paragraph  ) 

Get the max ascent value for all the fonts in the paragraph.

Parameters:
paragraph the pl_paragraph

Return the max ascent value for all the fonts in the paragraph.

Parameters:
paragraph the pl_paragraph
Returns:
the ascent value.
Internal:
Do not use. This API is for internal use only.
le_int32 pl_getDescent ( const pl_paragraph paragraph  ) 

Return the max descent value for all the fonts in the paragraph.

Parameters:
paragraph the pl_paragraph
Returns:
the decent value.
Internal:
Do not use. This API is for internal use only.
le_int32 pl_getLeading ( const pl_paragraph paragraph  ) 

Return the max leading value for all the fonts in the paragraph.

Parameters:
paragraph the pl_paragraph
Returns:
the leading value.
Internal:
Do not use. This API is for internal use only.
le_int32 pl_getLineAscent ( const pl_line line  ) 

Get the ascent of the line.

This is the maximum ascent of all the fonts on the line.

Parameters:
line the pl_line object.
Returns:
the ascent of the line.
Internal:
Do not use. This API is for internal use only.
le_int32 pl_getLineDescent ( const pl_line line  ) 

Get the descent of the line.

This is the maximum descent of all the fonts on the line.

Parameters:
line the pl_line object.
Returns:
the descent of the line.
Internal:
Do not use. This API is for internal use only.
le_int32 pl_getLineLeading ( const pl_line line  ) 

Get the leading of the line.

This is the maximum leading of all the fonts on the line.

Parameters:
line the pl_line object.
Returns:
the leading of the line.
Internal:
Do not use. This API is for internal use only.
const pl_visualRun* pl_getLineVisualRun ( const pl_line line,
le_int32  runIndex 
)

Get a ParagraphLayout::VisualRun object for a given visual run in the line.

Parameters:
line the pl_line object.
runIndex is the index of the run, in visual order.
Returns:
the pl_visualRun object representing the visual run. This object is owned by the pl_line object which created it, and will remain valid for as long as the pl_line object is valid.
See also:
pl_visualRun
Internal:
Do not use. This API is for internal use only.
le_int32 pl_getLineWidth ( const pl_line line  ) 

Get the width of the line.

This is a convenience method which returns the last X position of the last visual run in the line.

Parameters:
line the pl_line object.
Returns:
the width of the line.
Internal:
Do not use. This API is for internal use only.
UBiDiLevel pl_getParagraphLevel ( pl_paragraph paragraph  ) 

Return the resolved paragraph level.

This is useful for those cases where the bidi analysis has determined the level based on the first strong character in the paragraph.

Parameters:
paragraph the pl_paragraph
Returns:
the resolved paragraph level.
Internal:
Do not use. This API is for internal use only.
UBiDiDirection pl_getTextDirection ( pl_paragraph paragraph  ) 

Return the directionality of the text in the paragraph.

Parameters:
paragraph the pl_paragraph
Returns:
UBIDI_LTR if the text is all left to right, UBIDI_RTL if the text is all right to left, or UBIDI_MIXED if the text has mixed direction.
Internal:
Do not use. This API is for internal use only.
le_int32 pl_getVisualRunAscent ( const pl_visualRun run  ) 

A convenience method which returns the ascent value for the font associated with this run.

Parameters:
run the pl_visualRun object.
Returns:
the ascent value of this run's font.
Internal:
Do not use. This API is for internal use only.
le_int32 pl_getVisualRunDescent ( const pl_visualRun run  ) 

A convenience method which returns the descent value for the font associated with this run.

Parameters:
run the pl_visualRun object.
Returns:
the descent value of this run's font.
Internal:
Do not use. This API is for internal use only.
UBiDiDirection pl_getVisualRunDirection ( const pl_visualRun run  ) 

Get the direction of the visual run.

Parameters:
run the pl_visualRun object.
Returns:
the direction of the run. This will be UBIDI_LTR if the run is left-to-right and UBIDI_RTL if the line is right-to-left.
Internal:
Do not use. This API is for internal use only.
const le_font* pl_getVisualRunFont ( const pl_visualRun run  ) 

Get the le_font object which represents the font of the visual run.

This will always be a non-composite font.

Parameters:
run the pl_visualRun object.
Returns:
the le_font object which represents the font of the visual run.
See also:
le_font
Internal:
Do not use. This API is for internal use only.
le_int32 pl_getVisualRunGlyphCount ( const pl_visualRun run  ) 

Get the number of glyphs in the visual run.

Parameters:
run the pl_visualRun object.
Returns:
the number of glyphs.
Internal:
Do not use. This API is for internal use only.
const LEGlyphID* pl_getVisualRunGlyphs ( const pl_visualRun run  ) 

Get the glyphs in the visual run.

Glyphs with the values 0xFFFE and 0xFFFF should be ignored.

Parameters:
run the pl_visualRun object.
Returns:
the address of the array of glyphs for this visual run. The storage is owned by the pl_visualRun object and must not be deleted. It will remain valid as long as the pl_visualRun object is valid.
Internal:
Do not use. This API is for internal use only.
const le_int32* pl_getVisualRunGlyphToCharMap ( const pl_visualRun run  ) 

Get the glyph-to-character map for this visual run.

This maps the indices into the glyph array to indices into the character array used to create the paragraph.

Parameters:
run the pl_visualRun object.
Returns:
the address of the character-to-glyph map for this visual run. The storage is owned by the pl_visualRun object and must not be deleted. It will remain valid as long as the pl_visualRun object is valid.
Internal:
Do not use. This API is for internal use only.
le_int32 pl_getVisualRunLeading ( const pl_visualRun run  ) 

A convenience method which returns the leading value for the font associated with this run.

Parameters:
run the pl_visualRun object.
Returns:
the leading value of this run's font.
Internal:
Do not use. This API is for internal use only.
const float* pl_getVisualRunPositions ( const pl_visualRun run  ) 

Get the (x, y) positions of the glyphs in the visual run.

To simplify storage management, the x and y positions are stored in a single array with the x positions at even offsets in the array and the corresponding y position in the following odd offset. There is an extra (x, y) pair at the end of the array which represents the advance of the final glyph in the run.

Parameters:
run the pl_visualRun object.
Returns:
the address of the array of glyph positions for this visual run. The storage is owned by the pl_visualRun object and must not be deleted. It will remain valid as long as the pl_visualRun object is valid.
Internal:
Do not use. This API is for internal use only.
le_bool pl_isComplex ( const LEUnicode  chars[],
le_int32  count 
)

Examine the given text and determine if it contains characters in any script which requires complex processing to be rendered correctly.

Parameters:
chars is an array of the characters in the paragraph
count is the number of characters in the paragraph.
Returns:
TRUE if any of the text requires complex processing.
Internal:
Do not use. This API is for internal use only.
pl_line* pl_nextLine ( pl_paragraph paragraph,
float  width 
)

Return a pl_line object which represents next line in the paragraph.

The width of the line is specified each time so that it can be varied to support arbitrary paragraph shapes.

Parameters:
paragraph the pl_paragraph
width is the width of the line. If width is less than or equal to zero, a ParagraphLayout::Line object representing the rest of the paragraph will be returned.
Returns:
a ParagraphLayout::Line object which represents the line. The caller is responsible for deleting the object. Returns NULL if there are no more lines in the paragraph.
See also:
pl_line
Internal:
Do not use. This API is for internal use only.
void pl_reflow ( pl_paragraph paragraph  ) 

Reset line breaking to start from the beginning of the paragraph.

Parameters:
paragraph the pl_paragraph
Internal:
Do not use. This API is for internal use only.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on Sat Jan 23 15:17:36 2010 for ICU 4.3.4 by  doxygen 1.6.1