1Tickit::RenderBuffer(3pUms)er Contributed Perl DocumentatTiiocnkit::RenderBuffer(3pm)
2
6 "Tickit::RenderBuffer" - efficiently render text and line-drawing
7
9 package Tickit::Widget::Something;
10 ...
11 sub render_to_rb
13 {
14 my $self = shift;
15 my ( $rb, $rect ) = @_;
16 $rb->eraserect( $rect );
18 $rb->text_at( 2, 2, "Hello, world!", $self->pen );
19 }
20 $win->set_on_expose( sub {
22 my ( $win, $rb, $rect ) = @_;
23 $rb->eraserect( $rect );
25 $rb->text_at( 2, 2, "Hello, world!" );
26 });
27
29 Provides a buffer of pending rendering operations to apply to the
30 terminal. The buffer is modified by rendering operations performed by
31 widgets or other code, and flushed to the terminal when complete.
32 This provides the following advantages:
34 • Changes can be made in any order, and will be flushed in top-to-
36 bottom, left-to-right order, minimising cursor movements.
37 • Buffered content can be overwritten or partly erased once stored,
39 simplifying some styles of drawing operation. Large areas can be
40 erased, and then redrawn with text or lines, without causing a
41 double-drawing flicker on the output terminal.
42 • The buffer supports line-drawing, complete with merging of line
44 segments that meet in a character cell. Boxes, grids, and other
45 shapes can be easily formed by drawing separate line segments, and
46 the "RenderBuffer" will handle the corners and other junctions
47 formed.
48 • A single buffer can be passed around all of the windows or widgets to
50 properly combine line segments and layering effects, making it
51 possible to create many kinds of sub-divided or layered output.
52 Drawing methods come in two forms; absolute, and cursor-relative:
54 • Absolute methods, identified by their name having a suffixed "_at",
56 operate on a position within the buffer specified by their argument.
57 • Cursor-relative methods, identified by their lack of "_at" suffix,
59 operate at and update the position of the "virtual cursor". This is a
60 position within the buffer that can be set using the "goto" method.
61 The position of the virtual cursor is not affected by the absolute-
62 position methods.
63 State Stack
65 The "RenderBuffer" stores a stack of saved state. The state of the
66 buffer can be stored using the "save" method, so that changes can be
67 made, before finally restoring back to that state using "restore". The
68 following items of state are saved:
69 • The virtual cursor position
71 • The clipping rectangle
73 • The render pen
75 • The translation offset
77 • The set of masked regions
79 When the state is saved to the stack, the render pen is remembered and
81 merged with any pen set using the "setpen" method.
82 The queued content to render is not part of the state stack. It is
84 intended that the state stack be used to implement recursive delegation
85 of drawing operations down a tree of code, allowing child contexts to
86 be created by saving state and modifying it, to later restore it again
87 afterwards.
88
90 new
91 $rb = Tickit::RenderBuffer->new( %args )
92 Returns a new instance of a "Tickit::RenderBuffer".
94 Takes the following named arguments:
96 lines => INT
98 cols => INT
99 The size of the buffer area.
100
102 lines
103 cols
104 $lines = $rb->lines
105 $cols = $rb->cols
107 Returns the size of the buffer area
109 line
111 col
112 $line = $rb->line
113 $col = $rb->col
115 Returns the current position of the virtual cursor, or "undef" if it is
117 not set.
118 save
120 $rb->save
121 Pushes a new state-saving context to the stack, which can later be
123 returned to by the "restore" method.
124 savepen
126 $rb->savepen
127 Pushes a new state-saving context to the stack that only stores the
129 pen. This can later be returned to by the "restore" method, but will
130 only restore the pen. Other attributes such as the virtual cursor
131 position will be unaffected.
132 This may be more efficient for rendering runs of text in a different
134 pen, than multiple calls to "text" or "erase" using the same pen. For a
135 single call it is better just to pass a different pen directly.
136 restore
138 $rb->restore
139 Pops and restores a saved state previously created with "save".
141 clip
143 $rb->clip( $rect )
144 Restricts the clipping rectangle of drawing operations to be no further
146 than the limits of the given rectangle. This will apply to subsequent
147 rendering operations but does not affect existing content, nor the
148 actual rendering to the terminal.
149 Clipping rectangles cumulative; each call further restricts the drawing
151 region. To revert back to a larger drawing area, use the "save" and
152 "restore" stack.
153 mask
155 $rb->mask( $rect )
156 Masks off the given area against any further changes. This will apply
158 to subsequent rendering operations but does not affect the existing
159 content, nor the actual rendering to the terminal.
160 Areas within the clipping region may be arbitrarily masked. Masks are
162 scoped to the depth of the stack they are applied at; once the
163 "restore" method is invoked, any masks applied since its corresponding
164 "save" will be removed.
165 translate
167 $rb->translate( $downward, $rightward )
168 Applies a translation to the coordinate system used by "goto" and the
170 absolute-position methods *_at. After this call, all positions used
171 will be offset by the given amount.
172 reset
174 $rb->reset
175 Removes any pending changes and reverts the "RenderBuffer" to its
177 default empty state. Undefines the virtual cursor position, resets the
178 clipping rectangle, and clears the stack of saved state.
179 clear
181 $rb->clear( $pen )
182 Resets every cell in the buffer to an erased state. A shortcut to
184 calling "erase_at" for every line.
185 goto
187 $rb->goto( $line, $col )
188 Sets the position of the virtual cursor.
190 setpen
192 $rb->setpen( $pen )
193 Sets the rendering pen to use for drawing operations. If a pen is set
195 then a $pen argument is optional to any of the drawing methods. If a
196 pen argument is supplied as well as having a stored pen, then the
197 attributes are merged, with the directly-applied pen taking precedence.
198 Successive calls to this method will replace the active pen used, but
200 if there is a saved state on the stack it will be merged with the
201 rendering pen of the most recent saved state.
202 This method may be preferable to passing pens into multiple "text" or
204 "erase" calls as it may be more efficient than merging the same pen on
205 every call. If the original pen is still required afterwards, the
206 "savepen" / "restore" pair may be useful.
207 skip_at
209 $rb->skip_at( $line, $col, $len )
210 Sets the range of cells given to a skipped state. No content will be
212 drawn here, nor will any content existing on the terminal be erased.
213 Initially, or after calling "reset", all cells are set to this state.
215 skip
217 $rb->skip( $len )
218 Sets the range of cells at the virtual cursor position to a skipped
220 state, and updates the position.
221 skip_to
223 $rb->skip_to( $col )
224 Sets the range of cells from the virtual cursor position until before
226 the given column to a skipped state, and updates the position to the
227 column.
228 If the position is already past this column then the cursor is moved
230 backwards and no buffer changes are made.
231 skiprect
233 $rb->skiprect( $rect )
234 Sets the range of cells given by the rectangle to skipped state.
236 text_at
238 $cols = $rb->text_at( $line, $col, $text, $pen )
239 Sets the range of cells starting at the given position, to render the
241 given text in the given pen.
242 Returns the number of columns wide the actual $text is (which may be
244 more than was actually printed).
245 text
247 $cols = $rb->text( $text, $pen )
248 Sets the range of cells at the virtual cursor position to render the
250 given text in the given pen, and updates the position.
251 Returns the number of columns wide the actual $text is (which may be
253 more than was actually printed).
254 erase_at
256 $rb->erase_at( $line, $col, $len, $pen )
257 Sets the range of cells given to erase with the given pen.
259 erase
261 $rb->erase( $len, $pen )
262 Sets the range of cells at the virtual cursor position to erase with
264 the given pen, and updates the position.
265 erase_to
267 $rb->erase_to( $col, $pen )
268 Sets the range of cells from the virtual cursor position until before
270 the given column to erase with the given pen, and updates the position
271 to the column.
272 If the position is already past this column then the cursor is moved
274 backwards and no buffer changes are made.
275 eraserect
277 $rb->eraserect( $rect, $pen )
278 Sets the range of cells given by the rectangle to erase with the given
280 pen.
281
283 The "RenderBuffer" supports storing line-drawing characters in cells,
284 and can merge line segments where they meet, attempting to draw the
285 correct character for the segments that meet in each cell.
286 There are three exported constants giving supported styles of line
288 drawing:
289 • LINE_SINGLE
291 A single, thin line
293 • LINE_DOUBLE
295 A pair of double, thin lines
297 • LINE_THICK
299 A single, thick line
301 Note that linedrawing is performed by Unicode characters, and not every
303 possible combination of line segments of differing styles meeting in a
304 cell is supported by Unicode. The following sets of styles may be
305 relied upon:
306 • Any possible combination of only "SINGLE" segments, "THICK"
308 segments, or both.
309 • Any combination of only "DOUBLE" segments, except cells that only
311 have one of the four borders occupied.
312 • Any combination of "SINGLE" and "DOUBLE" segments except where the
314 style changes between "SINGLE" to "DOUBLE" on a vertical or
315 horizontal run.
316 Other combinations are not directly supported (i.e. any combination of
318 "DOUBLE" and "THICK" in the same cell, or any attempt to change from
319 "SINGLE" to "DOUBLE" in either the vertical or horizontal direction).
320 To handle these cases, a cell may be rendered with a substitution
321 character which replaces a "DOUBLE" or "THICK" segment with a "SINGLE"
322 one within that cell. The effect will be the overall shape of the line
323 is retained, but close to the edge or corner it will have the wrong
324 segment type.
325 Conceptually, every cell involved in line drawing has a potential line
327 segment type at each of its four borders to its neighbours. Horizontal
328 lines are drawn though the vertical centre of each cell, and vertical
329 lines are drawn through the horizontal centre.
330 There is a choice of how to handle the ends of line segments, as to
332 whether the segment should go to the centre of each cell, or should
333 continue through the entire body of the cell and stop at the boundary.
334 By default line segments will start and end at the centre of the cells,
335 so that horizontal and vertical lines meeting in a cell will form a
336 neat corner. When drawing isolated lines such as horizontal or vertical
337 rules, it is preferable that the line go right through the cells at the
338 start and end. To control this behaviour, the $caps bitmask is used.
339 "CAP_START" and "CAP_END" state that the line should consume the whole
340 of the start or end cell, respectively; "CAP_BOTH" is a convenient
341 shortcut specifying both behaviours.
342 A rectangle may be formed by combining two "hline_at" and two
344 "vline_at" calls, without end caps:
345 $rb->hline_at( $top, $left, $right, $style, $pen );
347 $rb->hline_at( $bottom, $left, $right, $style, $pen );
348 $rb->vline_at( $top, $bottom, $left, $style, $pen );
349 $rb->vline_at( $top, $bottom, $right, $style, $pen );
350 hline_at
352 $rb->hline_at( $line, $startcol, $endcol, $style, $pen, $caps )
353 Draws a horizontal line between the given columns (both are inclusive),
355 in the given line style, with the given pen.
356 vline_at
358 $rb->vline_at( $startline, $endline, $col, $style, $pen, $caps )
359 Draws a vertical line between the centres of the given lines (both are
361 inclusive), in the given line style, with the given pen.
362 linebox_at
364 $rb->linebox_at( $startline, $endline, $startcol, $endcol, $style, $pen )
365 A convenient shortcut to calling two "hline_at" and two "vline_at" in
367 order to draw a rectangular box.
368 char_at
370 $rb->char_at( $line, $col, $codepoint, $pen )
371 Sets the given cell to render the given Unicode character (as given by
373 codepoint number, not character string) in the given pen.
374 char
376 $rb->char( $codepoint, $pen )
377 Sets the cell at the virtual cursor position to render the given
379 Unicode character (as given by codepoint number, not character string)
380 in the given pen, and updates the position.
381 While this is also achieveable by the "text" and "text_at" methods,
383 these methods are implemented without storing a text segment, so can be
384 more efficient than many single-column wide "text_at" calls.
385 copyrect
387 moverect
388 $rb->copyrect( $dest, $src )
389 $rb->moverect( $dest, $src )
391 Copies (or moves) buffered content from one rectangular region to
393 another. The two regions may overlap.
394 The move operation is identical to the copy operation followed by
396 setting the vacated areas of the source rectangle not covered by the
397 destination to skipping state.
398 get_cell
400 $cell = $rb->get_cell( $line, $col )
401 Returns a structure containing the content stored in the given cell.
403 The $cell structure responds to the following methods:
404 $cell->char
406 On a skipped cell, returns "undef". On a text or char cell, returns
407 the unicode codepoint number. On a line or erased cell, returns 0.
408 $cell->linemask
410 On a line cell, returns a representation of the line segments in
411 the cell. This is a sub-structure with four fields; "north",
412 "south", "east", "west" to represent the four cell borders; the
413 value of each is either zero, or one of the "LINE_" constants.
414 On any other kind of cell, returns "undef".
416 $cell->pen
418 Returns the "Tickit::Pen" for non-skipped cells, or "undef" for
419 skipped cells.
420 flush_to_term
422 $rb->flush_to_term( $term )
423 Renders the stored content to the given Tickit::Term. After this, the
425 buffer will be cleared and reset back to initial state.
426
428 Paul Evans <leonerd@leonerd.org.uk>
429perl v5.38.0 2023-07-21 Tickit::RenderBuffer(3pm)