Kiva Interface Quick Reference (AGG backend)
==========================================================================

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.

-------------------------------------------
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
    affine_matrix: an AffineMatrix instance representing some type of
                   coordinate transform.  See /kiva/agg/src/kiva_affine_matrix.h
    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), ...)

-------------------------------------------
Supporting types
-------------------------------------------

  AffineMatrix
  ------------
  (kiva_affine_matrix.h and affine_matrix.i)
  All of the following member functions modify the instance on which they
  are called:

        __init__(v0, v1, v2, v3, v4, v5) or __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
        scale() -> float         # returns the average scale of this matrix
        determinant() -> float   # returns the determinant

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

        translation_matrix(float X, float Y)
        rotation_matrix(float angle_in_radians)
        scaling_matrix(float x_scale, float y_scale)
        skewing_matrix(float x_shear, float y_shear)

  FontType
  ------------
  (kiva_font_type.h and font_type.i)
  __init__(name, size=12)

  CompiledPath
  ------------
  see kiva_compiled_path.h in /kiva/agg/src/;
  interface is very similar to "Path drawing" interface of Graphics Context


-------------------------------------------
Enumerations - see also /kiva/agg/src/kiva_constants.h
-------------------------------------------
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, BOLD, ITALIC
    text_draw_mode: TEXT_FILL, TEXT_INVISIBLE  [this is currently unused]

    pix_format:
        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
        (NOTE: the strings in the dicts omit the "pix_format_" prefix)

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

    marker:
        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
        (NOTE: the strings in the dicts omit the "marker_" prefix)

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




*************************************************
***        Graphics Context Reference         ***
*************************************************

-------------------------------------------
Construction
-------------------------------------------
    GraphicsContextArray(size, pix_format="rgba32")
        # size is a tuple (width, height)
    Image(filename)


-------------------------------------------
Graphics state
-------------------------------------------
    save_state()
    restore_state()
    set_stroke_color(color)
    get_stroke_color() -> color
    set_line_width(float)
    set_line_join(line_join)
    set_line_cap(line_cap)
    set_line_dash(array)
        # array is an even-lengthed tuple of floats that represents
        # the width of each dash and gap in the dash pattern.
    set_fill_color(color)
    get_fill_color() -> color
    linear_gradient(x1, y1, x2, y2, stops, spread_method, units)
    radial_gradient(cx, cy, r, fx, fy, stops, spread_method, units)
        # The gradient methods modify the current fill color
    set_alpha(float)
    get_alpha() -> float
    set_antialias(bool)
    get_antialias() -> bool
    set_miter_limit(float)
    set_flatness(float)
    get_image_interpolation() -> interpolation
    set_image_interpolation(interpolation)

    translate_ctm(float x, float y)
    rotate_ctm(float angle_in_radians)
    concat_ctm(AffineMatrix)
    scale_ctm(float x_scale, float y_scale)
    set_ctm(AffineMatrix)
    get_ctm() -> AffineMatrix


-------------------------------------------
Clipping functions
-------------------------------------------
    clip_to_rect(rect)
    clip_to_rects(rect_array)
    clip()
        # clips using the current path
    even_odd_clip()
        # modifies the current clipping path using the even-odd rule to
        # calculate the intersection of the current path and the current
        # clipping path.

-------------------------------------------
Path construction functions
-------------------------------------------
    # All coordinates below are floating-point
    begin_path()
    close_path()
    get_empty_path() -> CompiledPath
        # returns a blank CompiledPath instance
    add_path(CompiledPath)

    move_to(x, y)
    line_to(x, y)
    lines(point_array)
    rect(x, y, w, h)
    rects(rect_array)

    curve_to(x1, y1, x2, y2, end_x, end_y)
        # draws a cubic bezier curve with control points (x1,y1) and (x2,y2)
        # that ends at point (end_x, end_y)

    quad_curve_to(cp_x, cp_y, end_x, end_y)
        # draws a quadratic bezier curve from the current point using
        # control point (cp_x, cp_y) and ending at (end_x, end_y)

    arc(x, y, radius, start_angle, end_angle, bool cw=false)
        # draws a circular arc of the given radius, centered at (x,y)
        # with angular span as indicated.  Angles are measured counter-
        # clockwise from the positive X axis.  If "cw" is true, then
        # the arc is swept from the end_angle back to the start_angle
        # (it does not change the sense in which the angles are measured).

    arc_to(x1, y1, x2, y2, radius)
        # from the comments in kiva_graphics_context_base.h:
        # Sweeps a circular arc from the pen position to a point on the
        # line from (x1,y1) to (x2,y2).
        #
        # The arc is tangent to the line from the current pen position
        # to (x1,y1), and it is also tangent to the line from (x1,y1)
        # to (x2,y2).  (x1,y1) is the imaginary intersection point of
        # the two lines tangent to the arc at the current point and
        # at (x2,y2).
        #
        # If the tangent point on the line from the current pen position
        # to (x1,y1) is not equal to the current pen position, a line is
        # drawn to it.  Depending on the supplied radius, the tangent
        # point on the line fron (x1,y1) to (x2,y2) may or may not be
        # (x2,y2).  In either case, the arc is drawn to the point of
        # tangency, which is also the new pen position.
        #
        # Consider the common case of rounding a rectangle's upper left
        # corner.  Let "r" be the radius of rounding.  Let the current
        # pen position be (x_left + r, y_top).  Then (x2,y2) would be
        # (x_left, y_top - radius), and (x1,y1) would be (x_left, y_top).

-------------------------------------------
Drawing functions
-------------------------------------------
    stroke_path()
    fill_path()
    eof_fill_path()
    draw_path(draw_mode=FILL_STROKE)
    draw_rect(rect, draw_mode=FILL_STROKE)
    draw_marker_at_points(point_array, int size, marker=marker_square)
    draw_path_at_points(point_array, CompiledPath, draw_mode)
    draw_image(graphics_context img, rect=None)
        # if rect is defined, then img is scaled and drawn into it;
        # otherwise, img is overlayed exactly on top of this graphics context

-------------------------------------------
Text functions
-------------------------------------------
    set_text_drawing_mode(text_draw_mode)
    set_text_matrix(AffineMatrix)
    get_text_matrix() -> AffineMatrix
    set_text_position(float X, float Y)
    get_text_position() -> (X, Y)
    show_text(string)
    show_text_translate(string, float X, float Y)
    get_text_extent(string) -> (x,y,w,h)
    get_full_text_extent(string) -> (w,h,x,y)
        # deprecated; order has been changed for backwards-compatibility
        # with existing Enable
    select_font(name, size, style)
    set_font(FontType)
    get_font() -> FontType
    set_font_size(int)
    set_character_spacing()
    get_character_spacing()
    set_text_drawing_mode()
    show_text_at_point()

-------------------------------------------
Misc functions
-------------------------------------------
    width() -> int
    height() -> int
    stride() -> int
    bottom_up() -> bool
    format() -> pix_format

    flush()
        # Force all pending drawing operations to be rendered immediately.
        # This only makes sense in window contexts, ie- the Mac Quartz backend.
    synchronize()
        # A deferred version of flush(). Also only relevant in window contexts.
    begin_page()
    end_page()

    clear_rect(rect)
        # Clears a rect. Not available in PDF context.

    convert_pixel_format(pix_format, bool inplace=0)

    save(filename, file_format=None, pil_options=None)
        # From the comments in graphics_context.i:
        # Save the GraphicsContext to a file.  Output files are always
        # saved in RGB or RGBA format; if this GC is not in one of
        # these formats, it is automatically converted.
        #
        # If filename includes an extension, the image format is
        # inferred from it.  file_format is only required if the
        # format can't be inferred from the filename (e.g. if you
        # wanted to save a PNG file as a .dat or .bin).
        #
        # pil_options is a dict of format-specific options that
        # are passed down to the PIL image file writer.  If a writer
        # doesn't recognize an option, it is silently ignored.
        #
        # If the image has an alpha channel and the specified output
        # file format does not support alpha, the image is saved in
        # rgb24 format.



-------------------------------------------
Functions that are currently stubbed
out or not implemented
-------------------------------------------
    show_glyphs_at_point()