1Tickit::RenderBuffer(3pUms)er Contributed Perl DocumentatTiiocnkit::RenderBuffer(3pm)
2
3
4

NAME

6       "Tickit::RenderBuffer" - efficiently render text and line-drawing
7

SYNOPSIS

9        package Tickit::Widget::Something;
10        ...
11
12        sub render_to_rb
13        {
14           my $self = shift;
15           my ( $rb, $rect ) = @_;
16
17           $rb->eraserect( $rect );
18           $rb->text_at( 2, 2, "Hello, world!", $self->pen );
19        }
20
21        $win->set_on_expose( sub {
22           my ( $win, $rb, $rect ) = @_;
23
24           $rb->eraserect( $rect );
25           $rb->text_at( 2, 2, "Hello, world!" );
26        });
27

DESCRIPTION

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
33       This provides the following advantages:
34
35       • Changes can be made in any order, and will be flushed in top-to-
36         bottom, left-to-right order, minimising cursor movements.
37
38       • 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
43       • 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
49       • 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
53       Drawing methods come in two forms; absolute, and cursor-relative:
54
55       • Absolute methods, identified by their name having a suffixed "_at",
56         operate on a position within the buffer specified by their argument.
57
58       • 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
64   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
70       • The virtual cursor position
71
72       • The clipping rectangle
73
74       • The render pen
75
76       • The translation offset
77
78       • The set of masked regions
79
80       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
83       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

CONSTRUCTOR

90   new
91          $rb = Tickit::RenderBuffer->new( %args )
92
93       Returns a new instance of a "Tickit::RenderBuffer".
94
95       Takes the following named arguments:
96
97       lines => INT
98       cols => INT
99               The size of the buffer area.
100

METHODS

102   lines
103   cols
104          $lines = $rb->lines
105
106          $cols = $rb->cols
107
108       Returns the size of the buffer area
109
110   line
111   col
112          $line = $rb->line
113
114          $col = $rb->col
115
116       Returns the current position of the virtual cursor, or "undef" if it is
117       not set.
118
119   save
120          $rb->save
121
122       Pushes a new state-saving context to the stack, which can later be
123       returned to by the "restore" method.
124
125   savepen
126          $rb->savepen
127
128       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
133       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
137   restore
138          $rb->restore
139
140       Pops and restores a saved state previously created with "save".
141
142   clip
143          $rb->clip( $rect )
144
145       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
150       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
154   mask
155          $rb->mask( $rect )
156
157       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
161       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
166   translate
167          $rb->translate( $downward, $rightward )
168
169       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
173   reset
174          $rb->reset
175
176       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
180   clear
181          $rb->clear( $pen )
182
183       Resets every cell in the buffer to an erased state.  A shortcut to
184       calling "erase_at" for every line.
185
186   goto
187          $rb->goto( $line, $col )
188
189       Sets the position of the virtual cursor.
190
191   setpen
192          $rb->setpen( $pen )
193
194       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
199       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
203       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
208   skip_at
209          $rb->skip_at( $line, $col, $len )
210
211       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
214       Initially, or after calling "reset", all cells are set to this state.
215
216   skip
217          $rb->skip( $len )
218
219       Sets the range of cells at the virtual cursor position to a skipped
220       state, and updates the position.
221
222   skip_to
223          $rb->skip_to( $col )
224
225       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
229       If the position is already past this column then the cursor is moved
230       backwards and no buffer changes are made.
231
232   skiprect
233          $rb->skiprect( $rect )
234
235       Sets the range of cells given by the rectangle to skipped state.
236
237   text_at
238          $cols = $rb->text_at( $line, $col, $text, $pen )
239
240       Sets the range of cells starting at the given position, to render the
241       given text in the given pen.
242
243       Returns the number of columns wide the actual $text is (which may be
244       more than was actually printed).
245
246   text
247          $cols = $rb->text( $text, $pen )
248
249       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
252       Returns the number of columns wide the actual $text is (which may be
253       more than was actually printed).
254
255   erase_at
256          $rb->erase_at( $line, $col, $len, $pen )
257
258       Sets the range of cells given to erase with the given pen.
259
260   erase
261          $rb->erase( $len, $pen )
262
263       Sets the range of cells at the virtual cursor position to erase with
264       the given pen, and updates the position.
265
266   erase_to
267          $rb->erase_to( $col, $pen )
268
269       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
273       If the position is already past this column then the cursor is moved
274       backwards and no buffer changes are made.
275
276   eraserect
277          $rb->eraserect( $rect, $pen )
278
279       Sets the range of cells given by the rectangle to erase with the given
280       pen.
281

LINE DRAWING

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
287       There are three exported constants giving supported styles of line
288       drawing:
289
290       •   LINE_SINGLE
291
292           A single, thin line
293
294       •   LINE_DOUBLE
295
296           A pair of double, thin lines
297
298       •   LINE_THICK
299
300           A single, thick line
301
302       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
307       •   Any possible combination of only "SINGLE" segments, "THICK"
308           segments, or both.
309
310       •   Any combination of only "DOUBLE" segments, except cells that only
311           have one of the four borders occupied.
312
313       •   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
317       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
326       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
331       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
343       A rectangle may be formed by combining two "hline_at" and two
344       "vline_at" calls, without end caps:
345
346        $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
351   hline_at
352          $rb->hline_at( $line, $startcol, $endcol, $style, $pen, $caps )
353
354       Draws a horizontal line between the given columns (both are inclusive),
355       in the given line style, with the given pen.
356
357   vline_at
358          $rb->vline_at( $startline, $endline, $col, $style, $pen, $caps )
359
360       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
363   linebox_at
364          $rb->linebox_at( $startline, $endline, $startcol, $endcol, $style, $pen )
365
366       A convenient shortcut to calling two "hline_at" and two "vline_at" in
367       order to draw a rectangular box.
368
369   char_at
370          $rb->char_at( $line, $col, $codepoint, $pen )
371
372       Sets the given cell to render the given Unicode character (as given by
373       codepoint number, not character string) in the given pen.
374
375   char
376          $rb->char( $codepoint, $pen )
377
378       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
382       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
386   copyrect
387   moverect
388          $rb->copyrect( $dest, $src )
389
390          $rb->moverect( $dest, $src )
391
392       Copies (or moves) buffered content from one rectangular region to
393       another.  The two regions may overlap.
394
395       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
399   get_cell
400          $cell = $rb->get_cell( $line, $col )
401
402       Returns a structure containing the content stored in the given cell.
403       The $cell structure responds to the following methods:
404
405       $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
409       $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
415           On any other kind of cell, returns "undef".
416
417       $cell->pen
418           Returns the "Tickit::Pen" for non-skipped cells, or "undef" for
419           skipped cells.
420
421   flush_to_term
422          $rb->flush_to_term( $term )
423
424       Renders the stored content to the given Tickit::Term. After this, the
425       buffer will be cleared and reset back to initial state.
426

AUTHOR

428       Paul Evans <leonerd@leonerd.org.uk>
429
430
431
432perl v5.38.0                      2023-07-21         Tickit::RenderBuffer(3pm)
Impressum