NAME
    `Tickit::RenderContext' - efficiently render text and linedrawing on
    Tickit windows

SYNOPSIS
     package Tickit::Widget::Something;
     ...

     sub render
     {
        my $self = shift;
        my %args = @_;
        my $win = $self->window or return;

        my $rc = Tickit::RenderContext->new(
           lines => $win->lines,
           cols  => $win->cols,
        );
        $rc->clip( $args{rect} );

        $rc->text_at( 2, 2, "Hello, world!", $self->pen );

        $rc->flush_to_window( $win );
     }

DESCRIPTION
    Provides a buffer of pending rendering operations to apply to a Window.
    The buffer is modified by rendering operations performed by the widget,
    and flushed to the widget's window when complete.

    This provides the following advantages:

    * Changes can be made in any order, and will be flushed in
      top-to-bottom, left-to-right order, minimising cursor movements.

    * Buffered content can be overwritten or partly erased once stored,
      simplifying some styles of drawing operation. Large areas can be
      erased, and then redrawn with text or lines, without causing a
      double-drawing flicker on the output terminal.

    * The buffer supports line-drawing, complete with merging of line
      segments that meet in a character cell. Boxes, grids, and other shapes
      can be easily formed by drawing separate line segments, and the render
      context will handle the corners and other junctions formed.

    Drawing methods come in two forms; absolute, and cursor-relative:

    * Absolute methods, identified by their name having a suffixed `_at',
      operate on a position within the buffer specified by their argument.

    * Cursor-relative methods, identified by their lack of `_at' suffix,
      operate at and update the position of the "virtual cursor". This is a
      position within the buffer that can be set using the `goto' method.
      The position of the virtual cursor is not affected by the
      absolute-position methods.

    This code is still in the experiment stage. At some future point it may
    be merged into the main Tickit distribution, and reimplemented in
    efficient XS or C code. As such, recommendations and best-practices are
    still subject to change and evolution as the code progresses.

  State Stack
    The render context stores a stack of saved state. The state of the
    context can be stored using the `save' method, so that changes can be
    made, before finally restoring back to that state using `restore'. The
    following items of state are saved:

    * The virtual cursor position

    * The clipping rectangle

    * The render pen

    * The translation offset

    When the state is saved to the stack, the render pen is remembered and
    merged with any pen set using the `setpen' method.

    The queued content to render is not part of the state stack. It is
    intended that the state stack be used to implement recursive delegation
    of drawing operations down a tree of code, allowing child contexts to be
    created by saving state and modifying it, to later restore it again
    afterwards.

CONSTRUCTOR
  $rc = Tickit::RenderContext->new( %args )
    Returns a new instance of a `Tickit::RenderContext'.

    Takes the following named arguments:

    lines => INT
    cols => INT
            The size of the buffer area.

METHODS
  $lines = $rc->lines
  $cols = $rc->cols
    Returns the size of the buffer area

  $rc->save
    Pushes a new state-saving context to the stack, which can later be
    returned to by the `restore' method.

  $rc->savepen
    Pushes a new state-saving context to the stack that only stores the pen.
    This can later be returned to by the `restore' method, but will only
    restore the pen. Other attributes such as the virtual cursor position
    will be unaffected.

    This may be more efficient for rendering runs of text in a different
    pen, than multiple calls to `text' or `erase' using the same pen. For a
    single call it is better just to pass a different pen directly.

  $rc->restore
    Pops and restores a saved state previously created with `save'.

  $rc->clip( $rect )
    Restricts the clipping rectangle of drawing operations to be no further
    than the limits of the given rectangle. This will apply to subsequent
    rendering operations but does not affect existing content, nor the
    actual rendering to the window.

    Clipping rectangles cumulative; each call further restricts the drawing
    region. To revert back to a larger drawing area, use the `save' and
    `restore' stack.

  $rc->translate( $downward, $rightward )
    Applies a translation to the coordinate system used by `goto' and the
    absolute-position methods `*_at'. After this call, all positions used
    will be offset by the given amount.

  $rc->reset
    Removes any pending changes and reverts the render context to its
    default empty state. Undefines the virtual cursor position, resets the
    clipping rectangle, and clears the stack of saved state.

  $rc->clear( $pen )
    Resets every cell in the buffer to an erased state. A shortcut to
    calling `erase_at' for every line.

  $rc->goto( $line, $col )
    Sets the position of the virtual cursor.

  $rc->setpen( $pen )
    Sets the rendering pen to use for drawing operations. If a pen is set
    then a `$pen' argument is optional to any of the drawing methods. If a
    pen argument is supplied as well as having a stored pen, then the
    attributes are merged, with the directly-applied pen taking precedence.

    Successive calls to this method will replace the active pen used, but if
    there is a saved state on the stack it will be merged with the rendering
    pen of the most recent saved state.

    This method may be preferrable to passing pens into multiple `text' or
    `erase' calls as it may be more efficient than merging the same pen on
    every call. If the original pen is still required afterwards, the
    `savepen' / `restore' pair may be useful.

  $rc->skip_at( $line, $col, $len )
    Sets the range of cells given to a skipped state. No content will be
    drawn here, nor will any content existing on the window be erased.

    Initially, or after calling `reset', all cells are set to this state.

  $rc->skip( $len )
    Sets the range of cells at the virtual cursor position to a skipped
    state, and updates the position.

  $rc->skip_to( $col )
    Sets the range of cells from the virtual cursor position until before
    the given column to a skipped state, and updates the position to the
    column.

    If the position is already past this column then the cursor is moved
    backwards and no buffer changes are made.

  $rc->text_at( $line, $col, $text, $pen )
    Sets the range of cells starting at the given position, to render the
    given text in the given pen.

  $rc->text( $text, $pen )
    Sets the range of cells at the virtual cursor position to render the
    given text in the given pen, and updates the position.

  $rc->erase_at( $line, $col, $len, $pen )
    Sets the range of cells given to erase with the given pen.

  $rc->erase( $len, $pen )
    Sets the range of cells at the virtual cursor position to erase with the
    given pen, and updates the position.

  $rc->erase_to( $col, $pen )
    Sets the range of cells from the virtual cursor position until before
    the given column to erase with the given pen, and updates the position
    to the column.

    If the position is already past this column then the cursor is moved
    backwards and no buffer changes are made.

LINE DRAWING
    The render context buffer supports storing line-drawing characters in
    cells, and can merge line segments where they meet, attempting to draw
    the correct character for the segments that meet in each cell.

    There are three exported constants giving supported styles of line
    drawing:

    * LINE_SINGLE
        A single, thin line

    * LINE_DOUBLE
        A pair of double, thin lines

    * LINE_THICK
        A single, thick line

    Note that linedrawing is performed by Unicode characters, and not every
    possible combination of line segments of differing styles meeting in a
    cell is supported by Unicode. The following sets of styles may be relied
    upon:

    *   Any possible combination of only `SINGLE' segments, `THICK'
        segments, or both.

    *   Any combination of only `DOUBLE' segments, except cells that only
        have one of the four borders occupied.

    *   Any combination of `SINGLE' and `DOUBLE' segments except where the
        style changes between `SINGLE' to `DOUBLE' on a vertical or
        horizontal run.

    Other combinations are not directly supported (i.e. any combination of
    `DOUBLE' and `THICK' in the same cell, or any attempt to change from
    `SINGLE' to `DOUBLE' in either the vertical or horizontal direction). To
    handle these cases, a cell may be rendered with a substitution character
    which replaces a `DOUBLE' or `THICK' segment with a `SINGLE' one within
    that cell. The effect will be the overall shape of the line is retained,
    but close to the edge or corner it will have the wrong segment type.

    Conceptually, every cell involved in line drawing has a potential line
    segment type at each of its four borders to its neighbours. Horizontal
    lines are drawn though the vertical centre of each cell, and vertical
    lines are drawn through the horizontal centre.

    There is a choice of how to handle the ends of line segments, as to
    whether the segment should go to the centre of each cell, or should
    continue through the entire body of the cell and stop at the boundary.
    By default line segments will start and end at the centre of the cells,
    so that horizontal and vertical lines meeting in a cell will form a neat
    corner. When drawing isolated lines such as horizontal or vertical
    rules, it is preferrable that the line go right through the cells at the
    start and end. To control this behaviour, the `$caps' bitmask is used.
    `CAP_START' and `CAP_END' state that the line should consume the whole
    of the start or end cell, respectively; `CAP_BOTH' is a convenient
    shortcut specifying both behaviours.

    A rectangle may be formed by combining two `hline_at' and two `vline_at'
    calls, without end caps:

     $rc->hline_at( $top,    $left, $right, $style, $pen );
     $rc->hline_at( $bottom, $left, $right, $style, $pen );
     $rc->vline_at( $top, $bottom, $left,  $style, $pen );
     $rc->vline_at( $top, $bottom, $right, $style, $pen );

  $rc->hline_at( $line, $startcol, $endcol, $style, $pen, $caps )
    Draws a horizontal line between the given columns (both are inclusive),
    in the given line style, with the given pen.

  $rc->vline_at( $startline, $endline, $col, $style, $pen, $caps )
    Draws a vertical line between the centres of the given lines (both are
    inclusive), in the given line style, with the given pen.

  $rc->char_at( $line, $col, $codepoint, $pen )
    Sets the given cell to render the given Unicode character (as given by
    codepoint number, not character string) in the given pen.

    While this is also achieveable by the `text_at' method, this method is
    implemented without storing a text segment, so can be more efficient
    than many single-column wide `text_at' calls. It will also be more
    efficient in the C library rewrite.

  $rc->flush_to_window( $win )
    Renders the stored content to the given Tickit::Window. After this, the
    context will be cleared and reset back to initial state.

TODO
    As this code is still experimental, there are many planned features it
    currently lacks:

    * Hole regions, to directly support shadows made by floating windows.

    * Direct rendering to a Tickit::Term instead of a Window.

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>