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)