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