Kiva Interface Quick Reference
==============================

This document is a summary of the classes and functions available in
Kiva.  More specifically, it describes some of the details of the
kiva.agg backend, including enumerated types and helper classes.

Graphics Context
----------------

Construction
~~~~~~~~~~~~
__init__(ary_or_size, pix_format="bgra32", base_pixel_scale=1.0):
    ``ary_or_size`` can be either a numpy array or a tuple of the form
    (width, height). If it is an array, it will be used as the backing store
    for the pixels. **Its shape must be compatible with** ``pix_format``

    ``pix_format`` determines the pixel format and is a string which can be any
    of the following: "gray8", "rgb24", "bgr24", "rgba32", "argb32", "abgr32",
    "bgra32".

    ``base_pixel_scale`` is scaling factor which will be applied to the
    transformation matrix before all other transformations. It is used for
    rendering to high-resolution displays.

State functions
~~~~~~~~~~~~~~~

Saving and restoring state
^^^^^^^^^^^^^^^^^^^^^^^^^^
In addtion to the ``save_state`` and ``restore_state`` methods, it is also possible
to use a ``GraphicsContext`` instance as a context manager.

.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.save_state
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.restore_state
  :noindex:

Methods controlling state
^^^^^^^^^^^^^^^^^^^^^^^^^

.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_fill_color
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_fill_color
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_stroke_color
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_stroke_color
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_line_width
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_line_join
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_line_cap
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_line_dash
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.linear_gradient
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.radial_gradient
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_alpha
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_alpha
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_antialias
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_antialias
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_miter_limit
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_flatness
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_image_interpolation
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_image_interpolation
  :noindex:


Current Transformation Matrix
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These methods control the affine transformation applied to drawing operations.
The current transformation matrix is part of the graphic state and therefore
covered by calls to ``save_state()`` and ``restore_state()``

.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.translate_ctm
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.rotate_ctm
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.scale_ctm
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.concat_ctm
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_ctm
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_ctm
  :noindex:


Clipping functions
~~~~~~~~~~~~~~~~~~

.. note::
   All of these functions are affected by the current transformation matrix.

.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.clip_to_rect
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.clip_to_rects
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.clip
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.even_odd_clip
  :noindex:


.. _kiva_path_functions:

Path functions
~~~~~~~~~~~~~~
The path has the concept of a "current point", which can be though of as the
pen position. Many path manipulations use the current point as a starting
position for the geometry which is added to the path.

.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.begin_path
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.close_path
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_empty_path
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.add_path
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.move_to
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.line_to
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.lines
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.line_set
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.rect
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.rects
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.curve_to
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.quad_curve_to
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.arc
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.arc_to
  :noindex:

.. _kiva_drawing_functions:

Drawing functions
~~~~~~~~~~~~~~~~~

.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.draw_path
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.fill_path
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.eof_fill_path
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.stroke_path
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.draw_rect
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.draw_image
  :noindex:

Enhanced drawing functions
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
   These methods are not available from every backend, so you should test for
   their presence before attempting to call them.

.. automethod:: kiva.abstract_graphics_context.EnhancedAbstractGraphicsContext.draw_marker_at_points
  :noindex:
.. automethod:: kiva.abstract_graphics_context.EnhancedAbstractGraphicsContext.draw_path_at_points
  :noindex:

Text functions
~~~~~~~~~~~~~~

.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_text_drawing_mode
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_text_matrix
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_text_matrix
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_text_position
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_text_position
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.show_text
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.show_text_at_point
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_text_extent
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_full_text_extent
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_character_spacing
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_character_spacing
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.select_font
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_font
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.get_font
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.set_font_size
  :noindex:


Misc functions
~~~~~~~~~~~~~~

.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.width
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.height
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.flush
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.synchronize
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.begin_page
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.end_page
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.clear_rect
  :noindex:
.. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.save
  :noindex:


Types
-----

Primitive types
~~~~~~~~~~~~~~~
The following conventions are used to describe input and output types:

color:
    Either a 3-tuple or 4-tuple. The represented color depends on the
    graphics context's pixel format.
rect:
    (origin_x, origin_y, width, height)
bool:
    an int that is 1 or 0
point_array:
    an array/sequence of length-2 arrays, e.g. ((x, y), (x2, y2),...)
rect_array:
    an array/sequence of rects ((x, y, w, h), (x2, y2, w2, h2), ...)
color_stop_array:
    an array/sequence of color stops ((offset, r, g, b, a),
    (offset2, r2, g2, b2, a2), ...) where offset is some number between 0 and 1
    inclusive and the entries are sorted from lowest offset to highest.

AffineMatrix
~~~~~~~~~~~~
All of the following member functions modify the instance on which they
are called:

* ``__init__(v0, v1, v2, v3, v4, v5)``
    also __init__()
* ``reset()``
    Sets this matrix to the identity
* ``multiply(AffineMatrix)``
    multiples this matrix by another.
* ``invert()``
    sets this matrix to the inverse of itself
* ``flip_x()``
    mirrors around X
* ``flip_y()``
    mirrors around Y

The rest of the member functions return information about the matrix.

* ``scale() -> float``
    returns the average scale of this matrix
* ``determinant() -> float``
    returns the determinant
* ``asarray() -> array``
    returns the matrix as a 1D numpy array of floats

The following factory methods are available in the top-level "agg" namespace
to create specific kinds of :class:`AffineMatrix` instances:

* ``translation_matrix(float x, float x)``
* ``rotation_matrix(float angle_in_radians)``
* ``scaling_matrix(float x_scale, float y_scale)``
* ``skewing_matrix(float x_shear, float y_shear)``

Enumerations
~~~~~~~~~~~~
The following enumerations are represented by top-level constants in the "agg"
namespace.  They are fundamentally integers.  Some of them also have dicts that
map between their names and integer values

line_cap:
    CAP_BUTT, CAP_ROUND, CAP_SQUARE
line_join:
    JOIN_ROUND, JOIN_BEVEL, JOIN_MITER
draw_mode:
    FILL, EOF_FILL, STROKE, FILL_STROKE, EOF_FILL_STROKE

text_style:
    NORMAL, ITALIC
text_weight:
    WEIGHT_NORMAL, WEIGHT_BOLD (some backends support additional weights)
text_draw_mode:
    TEXT_FILL, TEXT_STROKE, TEXT_FILL_STROKE, TEXT_INVISIBLE, TEXT_FILL_CLIP,
    TEXT_STROKE_CLIP, TEXT_FILL_STROKE_CLIP, TEXT_CLIP

pix_format:
    (NOTE: the strings in the dicts omit the ``pix_format_`` prefix)

    dicts:
        pix_format_string_map, pix_format_enum_map
    values:
        pix_format_gray8, pix_format_rgb555, pix_format_rgb565,
        pix_format_rgb24, pix_format_bgr24, pix_format_rgba32, pix_format_argb32,
        pix_format_abgr32, pix_format_bgra32

interpolation:
    dicts:
        interp_enum_map, interp_string_map
    values:
        nearest, bilinear, bicubic, spline16, spline36, sinc64, sinc144,
        sinc256, blackman64, blackman100, blackman256

marker:
    (NOTE: the strings in the dicts omit the ``marker_`` prefix)

    dicts:
        marker_string_map, marker_enum_map
    values:
        marker_circle, marker_cross, marker_crossed_circle, marker_dash,
        marker_diamond, marker_dot, marker_four_rays, marker_pixel,
        marker_semiellipse_down, marker_semiellipse_left, marker_x,
        marker_semiellipse_right, marker_semiellipse_up, marker_square,
        marker_triangle_down, marker_triangle_left, marker_triangle_right,
        marker_triangle_up

path_cmd and path_flags are low-level Agg path attributes.  See the Agg
documentation for more information about them.  We just pass them through in Kiva.

path_cmd:
    path_cmd_curve3, path_cmd_curve4, path_cmd_end_poly,
    path_cmd_line_to, path_cmd_mask, path_cmd_move_to, path_cmd_stop

path_flags:
    path_flags, path_flags_ccw, path_flags_close, path_flags_cw,
    path_flags_mask, path_flags_none
