citro2d
text.h
Go to the documentation of this file.
1 /**
2  * @file text.h
3  * @brief Text rendering API
4  */
5 #pragma once
6 #include "base.h"
7 #include "font.h"
8 
9 struct C2D_TextBuf_s;
10 typedef struct C2D_TextBuf_s* C2D_TextBuf;
11 
12 /** @defgroup Text Text drawing functions
13  * @{
14  */
15 
16 /// Text object.
17 typedef struct
18 {
19  C2D_TextBuf buf; ///< Buffer associated with the text.
20  size_t begin; ///< Reserved for internal use.
21  size_t end; ///< Reserved for internal use.
22  float width; ///< Width of the text in pixels, according to 1x scale metrics.
23  u32 lines; ///< Number of lines in the text.
24  u32 words; ///< Number of words in the text.
25  C2D_Font font; ///< Font used to draw the text, or NULL for system font
26 } C2D_Text;
27 
28 enum
29 {
30  C2D_AtBaseline = BIT(0), ///< Matches the Y coordinate with the baseline of the font.
31  C2D_WithColor = BIT(1), ///< Draws text with color. Requires a u32 color value.
32  C2D_AlignLeft = 0 << 2, ///< Draws text aligned to the left. This is the default.
33  C2D_AlignRight = 1 << 2, ///< Draws text aligned to the right.
34  C2D_AlignCenter = 2 << 2, ///< Draws text centered.
35  C2D_AlignJustified = 3 << 2, ///< Draws text justified. When C2D_WordWrap is not specified, right edge is x + scaleX*text->width. Otherwise, right edge is x + the width specified for those values.
36  C2D_AlignMask = 3 << 2, ///< Bitmask for alignment values.
37  C2D_WordWrap = BIT(4), ///< Draws text with wrapping of full words before specified width. Requires a float value, passed after color if C2D_WithColor is specified.
38 };
39 
40 /** @brief Creates a new text buffer.
41  * @param[in] maxGlyphs Maximum number of glyphs that can be stored in the buffer.
42  * @returns Text buffer handle (or NULL on failure).
43  */
44 C2D_TextBuf C2D_TextBufNew(size_t maxGlyphs);
45 
46 /** @brief Resizes a text buffer.
47  * @param[in] buf Text buffer to resize.
48  * @param[in] maxGlyphs Maximum number of glyphs that can be stored in the buffer.
49  * @returns New text buffer handle (or NULL on failure).
50  * @remarks If successful, old text buffer handle becomes invalid.
51  */
52 C2D_TextBuf C2D_TextBufResize(C2D_TextBuf buf, size_t maxGlyphs);
53 
54 
55 /** @brief Deletes a text buffer.
56  * @param[in] buf Text buffer handle.
57  * @remarks This also invalidates all text objects previously created with this buffer.
58  */
59 void C2D_TextBufDelete(C2D_TextBuf buf);
60 
61 /** @brief Clears all stored text in a buffer.
62  * @param[in] buf Text buffer handle.
63  */
64 void C2D_TextBufClear(C2D_TextBuf buf);
65 
66 /** @brief Retrieves the number of glyphs stored in a text buffer.
67  * @param[in] buf Text buffer handle.
68  * @returns The number of glyphs.
69  */
70 size_t C2D_TextBufGetNumGlyphs(C2D_TextBuf buf);
71 
72 /** @brief Parses and adds a single line of text to a text buffer.
73  * @param[out] text Pointer to text object to store information in.
74  * @param[in] buf Text buffer handle.
75  * @param[in] str String to parse.
76  * @param[in] lineNo Line number assigned to the text (used to calculate vertical position).
77  * @remarks Whitespace doesn't add any glyphs to the text buffer and is thus "free".
78  * @returns On success, a pointer to the character on which string processing stopped, which
79  * can be a newline ('\n'; indicating that's where the line ended), the null character
80  * ('\0'; indicating the end of the string was reached), or any other character
81  * (indicating the text buffer is full and no more glyphs can be added).
82  * On failure, NULL.
83  */
84 const char* C2D_TextParseLine(C2D_Text* text, C2D_TextBuf buf, const char* str, u32 lineNo);
85 
86 /** @brief Parses and adds a single line of text to a text buffer.
87  * @param[out] text Pointer to text object to store information in.
88  * @param[in] font Font to get glyphs from, or null for system font
89  * @param[in] buf Text buffer handle.
90  * @param[in] str String to parse.
91  * @param[in] lineNo Line number assigned to the text (used to calculate vertical position).
92  * @remarks Whitespace doesn't add any glyphs to the text buffer and is thus "free".
93  * @returns On success, a pointer to the character on which string processing stopped, which
94  * can be a newline ('\n'; indicating that's where the line ended), the null character
95  * ('\0'; indicating the end of the string was reached), or any other character
96  * (indicating the text buffer is full and no more glyphs can be added).
97  * On failure, NULL.
98  */
99 const char* C2D_TextFontParseLine(C2D_Text* text, C2D_Font font, C2D_TextBuf buf, const char* str, u32 lineNo);
100 
101 /** @brief Parses and adds arbitrary text (including newlines) to a text buffer.
102  * @param[out] text Pointer to text object to store information in.
103  * @param[in] buf Text buffer handle.
104  * @param[in] str String to parse.
105  * @remarks Whitespace doesn't add any glyphs to the text buffer and is thus "free".
106  * @returns On success, a pointer to the character on which string processing stopped, which
107  * can be the null character ('\0'; indicating the end of the string was reached),
108  * or any other character (indicating the text buffer is full and no more glyphs can be added).
109  * On failure, NULL.
110  */
111 const char* C2D_TextParse(C2D_Text* text, C2D_TextBuf buf, const char* str);
112 
113 /** @brief Parses and adds arbitrary text (including newlines) to a text buffer.
114  * @param[out] text Pointer to text object to store information in.
115  * @param[in] font Font to get glyphs from, or null for system font
116  * @param[in] buf Text buffer handle.
117  * @param[in] str String to parse.
118  * @remarks Whitespace doesn't add any glyphs to the text buffer and is thus "free".
119  * @returns On success, a pointer to the character on which string processing stopped, which
120  * can be the null character ('\0'; indicating the end of the string was reached),
121  * or any other character (indicating the text buffer is full and no more glyphs can be added).
122  * On failure, NULL.
123  */
124 const char* C2D_TextFontParse(C2D_Text* text, C2D_Font font, C2D_TextBuf buf, const char* str);
125 
126 /** @brief Optimizes a text object in order to be drawn more efficiently.
127  * @param[in] text Pointer to text object.
128  */
129 void C2D_TextOptimize(const C2D_Text* text);
130 
131 /** @brief Retrieves the total dimensions of a text object.
132  * @param[in] text Pointer to text object.
133  * @param[in] scaleX Horizontal size of the font. 1.0f corresponds to the native size of the font.
134  * @param[in] scaleY Vertical size of the font. 1.0f corresponds to the native size of the font.
135  * @param[out] outWidth (optional) Variable in which to store the width of the text.
136  * @param[out] outHeight (optional) Variable in which to store the height of the text.
137  */
138 void C2D_TextGetDimensions(const C2D_Text* text, float scaleX, float scaleY, float* outWidth, float* outHeight);
139 
140 /** @brief Draws text using the GPU.
141  * @param[in] text Pointer to text object.
142  * @param[in] flags Text drawing flags.
143  * @param[in] x Horizontal position to draw the text on.
144  * @param[in] y Vertical position to draw the text on. If C2D_AtBaseline is not specified (default), this
145  * is the top left corner of the block of text; otherwise this is the position of the baseline
146  * of the first line of text.
147  * @param[in] z Depth value of the text. If unsure, pass 0.0f.
148  * @param[in] scaleX Horizontal size of the font. 1.0f corresponds to the native size of the font.
149  * @param[in] scaleY Vertical size of the font. 1.0f corresponds to the native size of the font.
150  * @remarks The default 3DS system font has a glyph height of 30px, and the baseline is at 25px.
151  */
152 void C2D_DrawText(const C2D_Text* text, u32 flags, float x, float y, float z, float scaleX, float scaleY, ...);
153 
154 /** @} */
C2D_DrawText
void C2D_DrawText(const C2D_Text *text, u32 flags, float x, float y, float z, float scaleX, float scaleY,...)
Draws text using the GPU.
C2D_AtBaseline
Matches the Y coordinate with the baseline of the font.
Definition: text.h:30
C2D_Text
Text object.
Definition: text.h:17
C2D_TextFontParseLine
const char * C2D_TextFontParseLine(C2D_Text *text, C2D_Font font, C2D_TextBuf buf, const char *str, u32 lineNo)
Parses and adds a single line of text to a text buffer.
C2D_Text::begin
size_t begin
Reserved for internal use.
Definition: text.h:20
C2D_AlignLeft
Draws text aligned to the left. This is the default.
Definition: text.h:32
C2D_TextBufNew
C2D_TextBuf C2D_TextBufNew(size_t maxGlyphs)
Creates a new text buffer.
C2D_WithColor
Draws text with color. Requires a u32 color value.
Definition: text.h:31
C2D_Text::end
size_t end
Reserved for internal use.
Definition: text.h:21
C2D_Text::width
float width
Width of the text in pixels, according to 1x scale metrics.
Definition: text.h:22
C2D_TextParseLine
const char * C2D_TextParseLine(C2D_Text *text, C2D_TextBuf buf, const char *str, u32 lineNo)
Parses and adds a single line of text to a text buffer.
C2D_TextOptimize
void C2D_TextOptimize(const C2D_Text *text)
Optimizes a text object in order to be drawn more efficiently.
C2D_TextFontParse
const char * C2D_TextFontParse(C2D_Text *text, C2D_Font font, C2D_TextBuf buf, const char *str)
Parses and adds arbitrary text (including newlines) to a text buffer.
C2D_TextBufClear
void C2D_TextBufClear(C2D_TextBuf buf)
Clears all stored text in a buffer.
C2D_TextBufDelete
void C2D_TextBufDelete(C2D_TextBuf buf)
Deletes a text buffer.
C2D_Text::buf
C2D_TextBuf buf
Buffer associated with the text.
Definition: text.h:19
C2D_TextGetDimensions
void C2D_TextGetDimensions(const C2D_Text *text, float scaleX, float scaleY, float *outWidth, float *outHeight)
Retrieves the total dimensions of a text object.
C2D_WordWrap
Draws text with wrapping of full words before specified width. Requires a float value, passed after color if C2D_WithColor is specified.
Definition: text.h:37
C2D_AlignRight
Draws text aligned to the right.
Definition: text.h:33
C2D_TextBufResize
C2D_TextBuf C2D_TextBufResize(C2D_TextBuf buf, size_t maxGlyphs)
Resizes a text buffer.
C2D_AlignJustified
Draws text justified. When C2D_WordWrap is not specified, right edge is x + scaleX*text->width. Otherwise, right edge is x + the width specified for those values.
Definition: text.h:35
C2D_AlignMask
Bitmask for alignment values.
Definition: text.h:36
base.h
Basic citro2d initialization and drawing API.
C2D_TextParse
const char * C2D_TextParse(C2D_Text *text, C2D_TextBuf buf, const char *str)
Parses and adds arbitrary text (including newlines) to a text buffer.
C2D_Text::words
u32 words
Number of words in the text.
Definition: text.h:24
C2D_Text::lines
u32 lines
Number of lines in the text.
Definition: text.h:23
C2D_Text::font
C2D_Font font
Font used to draw the text, or NULL for system font.
Definition: text.h:25
C2D_TextBufGetNumGlyphs
size_t C2D_TextBufGetNumGlyphs(C2D_TextBuf buf)
Retrieves the number of glyphs stored in a text buffer.
font.h
Font loading and management.
C2D_AlignCenter
Draws text centered.
Definition: text.h:34
Generated by   doxygen 1.8.11