Provided by: libtickit-dev_0.4.2a-1_amd64 
NAME
TickitRenderBuffer - store display content to be drawn to the terminal
SYNOPSIS
#include <tickit.h>
typedef struct TickitRenderBuffer;
DESCRIPTION
A TickitRenderBuffer instance stores content waiting to be drawn to the terminal. It
provides an efficient place to build the eventual display, by applying drawing operations
to it that can alter and overwrite the pending content, before eventually flushing it
directly to the terminal in an efficient transfer of state. The buffer stores plain text
content along with rendering attributes, and also stores line drawing information,
allowing line segments to be merged correctly and rendered using Unicode characters.
The primary purpose for the render buffer is the storage of pending content to be
displayed. The buffer consists of a grid of cells of the given size. Each cell has a
state; neighbouring cells in the same state constitute a region. Each region is either in
a skip state (where it will not affect the terminal display when it is flushed), or has
either textual content or an instruction to erase the display. In both of these cases, the
region has an associated TickitPen instance to give its display attributes. Text regions
can be given either by UTF-8 strings, individual Unicode codepoint numbers, or are created
as Unicode line-drawing characters by merging one or more effective line segments.
There are several advantages to using a TickitRenderBuffer over plain drawing requests
directly to the terminal. Firstly, because the content is simply stored in memory until it
is flushed to the terminal, it doesn't have to be rendered in screen order. It can be
built up in any order that makes sense within the application, and when flushed to the
terminal it will be performed in an efficient top-to-bottom, left-to-right order.
Secondly, the buffer understands horizontal and vertical line drawing using Unicode
characters. While content is being built up, it will keep track of what kinds of lines
meet in every cell in the buffer, so that when it is flushed to the terminal it can pick
the appropriate Unicode line-drawing characters to render these with.
Thirdly, several features of the buffer are designed to easily support applications that
divide the screen area into several possibly-overlapping regions that are managed by
different parts of the application. Clipping, translation and masking support the concept
of independent areas of the buffer, and stored pens and the state stack support the
concept that these areas might be nested within each other, allowing rendering attributes
to be inherited from outer regions into inner ones.
VIRTUAL CURSOR
A TickitRenderBuffer instance maintains a virtual cursor position, that application code
can use to render at. This is a virtual cursor, because it doesn't relate to the actual
cursor in use on the terminal instance; it is simply a position stored by the buffer
state.
Most of the content drawing functions come in pairs; one using and updating the cursor
position, and a second that operates directly on the buffer contents, without regard to
the virtual cursor. Functions of this latter form can be identified by the _at suffix on
their name.
PEN
A TickitPen instance can be set on a TickitRenderBuffer, acting as a default pen for
subsequent drawing functions. This is optionally combined with a pen instance given to
individual drawing functions; if both are present then the attributes are combined, with
those of the given pen taking precedence over the ones in the stored pen.
TRANSLATION
A translation offset can be applied to have the drawing functions store their output at
some other location within the buffer. This translation only affects the drawing
functions; the actual operation to flush the contents to the terminal is not affected.
CLIPPING AND MASKING
All of the drawing functions are also subject to restriction of their output, to apply
within a clipping region. Initially the entire buffer is available for drawing, but the
area can be restricted to a smaller rectangular area at any time. Requests to draw content
outside of this region will be ignored.
In addition to clipping, a buffer can also mask out arbitrary additional rectangular areas
within the clipping region. These areas act with the clipping region by ignoring requests
to draw inside them while preserving any existing content within them.
Masking and clipping are related but separate concepts. Both place restrictions on where
output functions can alter the pending content. Whereas the clipping region is the
rectangular area within which all drawing occurs, masking regions are areas in which
drawing does not occur.
When combined with translation, these two features allow possibly-overlapping regions of
content to be independently managed by separate pieces of code. To render each region of
the screen, a render buffer can be set up with a translation offset and clipping rectangle
to suit that region, thus avoiding the rendering code having to care about the exact on-
screen geometry. By using masking regions, additionally these areas can be managed even
when they overlap, by ensuring that areas already drawn by "higher" regions are masked off
to ensure that "lower" regions do not overwrite them.
SAVE STACK
As a further assistance to applications wishing to divide the screen area into nested
regions, a set of functions exist to store the current auxiliary state of the buffer (that
is, all of the mutable attributes listed above, but without the actual pending content)
and later restore that state to its original values.
FUNCTIONS
A new TickitRenderBuffer instance is created using tickit_renderbuffer_new(3). A render
buffer instance stores a reference count to make it easier for applications to manage the
lifetime of buffers. A new buffer starts with a count of one, and it can be adjusted using
tickit_renderbuffer_ref(3) and tickit_renderbuffer_unref(3). When the count reaches zero
the instance is destroyed.
Its size is fixed after creation and can be queried using tickit_renderbuffer_get_size(3).
Its contents can be entirely reset back to its original state using
tickit_renderbuffer_reset(3).
A translation offset can be set using tickit_renderbuffer_translate(3), and the clipping
region restricted using tickit_renderbuffer_clip(3). Masks can be placed within the
current clipping region using tickit_renderbuffer_mask(3).
The virtual cursor position can be set using tickit_renderbuffer_goto(3) and unset using
tickit_renderbuffer_ungoto(3). It can be queried using
tickit_renderbuffer_has_cursorpos(3) to determine if it is set, and
tickit_renderbuffer_get_cursorpos(3) to return its position. A TickitPen instance can be
set using tickit_renderbuffer_setpen(3).
The auxiliary state can be saved to the state stack using tickit_renderbuffer_save(3) and
later restored using tickit_renderbuffer_restore(3). A stack state consisting of just the
pen with no other state can be saved using tickit_renderbuffer_savepen(3).
The stored content of a buffer can be copied to another buffer using
tickit_renderbuffer_blit(3). This is useful for allowing a window to maintain a backing
buffer that can be drawn to at any time and then copied to a destination buffer for
display.
The stored content can be flushed to a TickitTerm instance using
tickit_renderbuffer_flush_to_term(3).
DRAWING OPERATIONS
The following functions all affect the stored content within the buffer, taking into
account the clipping, translation, masking, stored pen, and optionally the virtual cursor
position.
tickit_renderbuffer_skip_at(3), tickit_renderbuffer_skip(3),
tickit_renderbuffer_skip_to(3) and tickit_renderbuffer_skiprect(3) create a skipping
region; a place where no output will be drawn.
tickit_renderbuffer_text_at(3) and tickit_renderbuffer_text(3) create a text region; a
place where normal text is output.
tickit_renderbuffer_erase_at(3), tickit_renderbuffer_erase(3) and
tickit_renderbuffer_erase_to(3) create an erase region; a place where existing terminal
content will be erased. tickit_renderbuffer_eraserect(3) is a convenient shortcut that
erases a rectangle, and tickit_renderbuffer_clear(3) erases the entire buffer area.
tickit_renderbuffer_char_at(3) and tickit_renderbuffer_char(3) place a single Unicode
character directly.
tickit_renderbuffer_hline_at(3) and tickit_renderbuffer_vline_at(3) create horizontal and
vertical line segments.
SEE ALSO
tickit(7), tickit_pen(7), tickit_rect(7) tickit_term(7)
TICKIT_RENDERBUFFER(7)