Provided by: libtickit-dev_0.2-5_amd64 bug

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 auxilliary 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 auxilliary 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)