1TICKIT_RENDERBUFFER(7) Miscellaneous Information Manual TICKIT_RENDERBUFFER(7)
2
6 TickitRenderBuffer - store display content to be drawn to the terminal
7
9 #include <tickit.h>
10 typedef struct TickitRenderBuffer;
12
15 A TickitRenderBuffer instance stores content waiting to be drawn to the
16 terminal. It provides an efficient place to build the eventual display,
17 by applying drawing operations to it that can alter and overwrite the
18 pending content, before eventually flushing it directly to the terminal
19 in an efficient transfer of state. The buffer stores plain text content
20 along with rendering attributes, and also stores line drawing informa‐
21 tion, allowing line segments to be merged correctly and rendered using
22 Unicode characters.
23 The primary purpose for the render buffer is the storage of pending
25 content to be displayed. The buffer consists of a grid of cells of the
26 given size. Each cell has a state; neighbouring cells in the same state
27 constitute a region. Each region is either in a skip state (where it
28 will not affect the terminal display when it is flushed), or has either
29 textual content or an instruction to erase the display. In both of
30 these cases, the region has an associated TickitPen instance to give
31 its display attributes. Text regions can be given either by UTF-8
32 strings, individual Unicode codepoint numbers, or are created as Uni‐
33 code line-drawing characters by merging one or more effective line seg‐
34 ments.
35 There are several advantages to using a TickitRenderBuffer over plain
37 drawing requests directly to the terminal. Firstly, because the content
38 is simply stored in memory until it is flushed to the terminal, it
39 doesn't have to be rendered in screen order. It can be built up in any
40 order that makes sense within the application, and when flushed to the
41 terminal it will be performed in an efficient top-to-bottom, left-to-
42 right order.
43 Secondly, the buffer understands horizontal and vertical line drawing
45 using Unicode characters. While content is being built up, it will keep
46 track of what kinds of lines meet in every cell in the buffer, so that
47 when it is flushed to the terminal it can pick the appropriate Unicode
48 line-drawing characters to render these with.
49 Thirdly, several features of the buffer are designed to easily support
51 applications that divide the screen area into several possibly-overlap‐
52 ping regions that are managed by different parts of the application.
53 Clipping, translation and masking support the concept of independent
54 areas of the buffer, and stored pens and the state stack support the
55 concept that these areas might be nested within each other, allowing
56 rendering attributes to be inherited from outer regions into inner
57 ones.
58 VIRTUAL CURSOR
60 A TickitRenderBuffer instance maintains a virtual cursor position, that
61 application code can use to render at. This is a virtual cursor,
62 because it doesn't relate to the actual cursor in use on the terminal
63 instance; it is simply a position stored by the buffer state.
64 Most of the content drawing functions come in pairs; one using and
66 updating the cursor position, and a second that operates directly on
67 the buffer contents, without regard to the virtual cursor. Functions of
68 this latter form can be identified by the _at suffix on their name.
69 PEN
71 A TickitPen instance can be set on a TickitRenderBuffer, acting as a
72 default pen for subsequent drawing functions. This is optionally com‐
73 bined with a pen instance given to individual drawing functions; if
74 both are present then the attributes are combined, with those of the
75 given pen taking precedence over the ones in the stored pen.
76 TRANSLATION
78 A translation offset can be applied to have the drawing functions store
79 their output at some other location within the buffer. This translation
80 only affects the drawing functions; the actual operation to flush the
81 contents to the terminal is not affected.
82 CLIPPING AND MASKING
84 All of the drawing functions are also subject to restriction of their
85 output, to apply within a clipping region. Initially the entire buffer
86 is available for drawing, but the area can be restricted to a smaller
87 rectangular area at any time. Requests to draw content outside of this
88 region will be ignored.
89 In addition to clipping, a buffer can also mask out arbitrary addi‐
91 tional rectangular areas within the clipping region. These areas act
92 with the clipping region by ignoring requests to draw inside them while
93 preserving any existing content within them.
94 Masking and clipping are related but separate concepts. Both place
96 restrictions on where output functions can alter the pending content.
97 Whereas the clipping region is the rectangular area within which all
98 drawing occurs, masking regions are areas in which drawing does not
99 occur.
100 When combined with translation, these two features allow possibly-over‐
102 lapping regions of content to be independently managed by separate
103 pieces of code. To render each region of the screen, a render buffer
104 can be set up with a translation offset and clipping rectangle to suit
105 that region, thus avoiding the rendering code having to care about the
106 exact on-screen geometry. By using masking regions, additionally these
107 areas can be managed even when they overlap, by ensuring that areas
108 already drawn by "higher" regions are masked off to ensure that "lower"
109 regions do not overwrite them.
110 SAVE STACK
112 As a further assistance to applications wishing to divide the screen
113 area into nested regions, a set of functions exist to store the current
114 auxilliary state of the buffer (that is, all of the mutable attributes
115 listed above, but without the actual pending content) and later restore
116 that state to its original values.
117
119 A new TickitRenderBuffer instance is created using tickit_render‐
120 buffer_new(3). A render buffer instance stores a reference count to
121 make it easier for applications to manage the lifetime of buffers. A
122 new buffer starts with a count of one, and it can be adjusted using
123 tickit_renderbuffer_ref(3) and tickit_renderbuffer_unref(3). When the
124 count reaches zero the instance is destroyed.
125 Its size is fixed after creation and can be queried using tickit_ren‐
127 derbuffer_get_size(3). Its contents can be entirely reset back to its
128 original state using tickit_renderbuffer_reset(3).
129 A translation offset can be set using tickit_renderbuffer_translate(3),
131 and the clipping region restricted using tickit_renderbuffer_clip(3).
132 Masks can be placed within the current clipping region using
133 tickit_renderbuffer_mask(3).
134 The virtual cursor position can be set using tickit_render‐
136 buffer_goto(3) and unset using tickit_renderbuffer_ungoto(3). It can be
137 queried using tickit_renderbuffer_has_cursorpos(3) to determine if it
138 is set, and tickit_renderbuffer_get_cursorpos(3) to return its posi‐
139 tion. A TickitPen instance can be set using tickit_renderbuffer_set‐
140 pen(3).
141 The auxilliary state can be saved to the state stack using tickit_ren‐
143 derbuffer_save(3) and later restored using tickit_render‐
144 buffer_restore(3). A stack state consisting of just the pen with no
145 other state can be saved using tickit_renderbuffer_savepen(3).
146 The stored content of a buffer can be copied to another buffer using
148 tickit_renderbuffer_blit(3). This is useful for allowing a window to
149 maintain a backing buffer that can be drawn to at any time and then
150 copied to a destination buffer for display.
151 The stored content can be flushed to a TickitTerm instance using
153 tickit_renderbuffer_flush_to_term(3).
154
156 The following functions all affect the stored content within the buf‐
157 fer, taking into account the clipping, translation, masking, stored
158 pen, and optionally the virtual cursor position.
159 tickit_renderbuffer_skip_at(3), tickit_renderbuffer_skip(3),
161 tickit_renderbuffer_skip_to(3) and tickit_renderbuffer_skiprect(3) cre‐
162 ate a skipping region; a place where no output will be drawn.
163 tickit_renderbuffer_text_at(3) and tickit_renderbuffer_text(3) create a
165 text region; a place where normal text is output.
166 tickit_renderbuffer_erase_at(3), tickit_renderbuffer_erase(3) and
168 tickit_renderbuffer_erase_to(3) create an erase region; a place where
169 existing terminal content will be erased. tickit_render‐
170 buffer_eraserect(3) is a convenient shortcut that erases a rectangle,
171 and tickit_renderbuffer_clear(3) erases the entire buffer area.
172 tickit_renderbuffer_char_at(3) and tickit_renderbuffer_char(3) place a
174 single Unicode character directly.
175 tickit_renderbuffer_hline_at(3) and tickit_renderbuffer_vline_at(3)
177 create horizontal and vertical line segments.
178
180 tickit(7), tickit_pen(7), tickit_rect(7) tickit_term(7)
181 TICKIT_RENDERBUFFER(7)