cairo/TODO

API Shakeup planning
--------------------
 Patch submitted to mailing list?
/ Documentation included in patch?
|/ Review of patch completed?
||/ Test case included?
|||/ Committed.
||||/
Somewhat backwards-compatible changes
-----------------------------------
PDRTC	user data (was Re: [cairo] Patch improving fallbacks)
PDRTC	setters and getters
PDR C	cairo_output_stream_t and cairo_surface_finish()
PDRTC	cairo_current_path -> cairo_copy_path_data
PDR C	cairo_surface_finish, cairo_surface_flush
PDR C	Abbreviation hunt: cairo_init_clip and cairo_concat_matrix
-----	Renaming the terms of the rendering equation
PDR C	default matrix
PDRTC	cairo_paint
	cairo_begin_group, cairo_end_group, cairo_get_group
PDRTC	Making set_source consistent
-----	cairo_stroke_path -> cairo_stroke_to_path
PDRTC	cairo_current_matrix
	cairo_mask
	cairo_create and eliminating cairo_set_target_surface
PDRTC	cairo_fill_preserve, cairo_stroke_preserve, cairo_clip_preserve
	cairo_<device>_surface_mark_dirty
PDR C	A hidden offset for the xlib backend
	Simplifying the operator set
	Consistent error handling for all objects

Backwards incompatible
----------------------
	Eliminating cairo_copy
	Eliminating cairo_surface_set_repeat/matrix/filter
	Eliminating cairo_show_surface

* Add support for non-antialiased rendering. API ?

* Clean up the cache code a bit, (there is at least one redundant
  level of cacheing, and there are some minor style issues).

* Add CAIRO_FILL_RULE_INVERSE_WINDING and CAIRO_FILL_RULE_INVERSE_EVEN_ODD

* Fix clipping to work for all operators. The equation we have come up
  with is:

	((src Op dest) In clip) Add (dest Out clip)

* Split cairo_format_t into two things:

   - An enumeration that determines the "capabilities" of a surface - 
     A vs. ARGB. vs. RGB
   - An enumeration that determines a specific in-memory representation
     of data. (A1/A8/ARGB32/etc.. Could be extensible to things like
     RGBA32_BYTES_NONPREMULTIPLIED. Some consistent naming convention would 
     be be good.)

  One issue here is that some interfaces, like cairo_surface_create_similar()
  might be useful with either one. We might want to create an A1 surface
  compatible with the backend (are there examples other than A1? Should 
  bilevel just be another "capability"?), or we might want to just create
  an alpha surface without caring about the depth.

  If we want to support this, we could do something like:

   typedef enum cairo_pixel_format_t {
     CAIRO_PIXEL_FORMAT_A8 = CAIRO_FORMAT_ALPHA,
     CAIRO_PIXEL_FORMAT_RGB24 = CAIRO_FORMAT_RGB,
     CAIRO_PIXEL_FORMAT_A1,
   };

  To allow passing either in. 

  (I don't particularly like this idea for create_similar() because then you 
  aren't really saying ALPHA-dont-care, you are saying ALPHA-8. I think it 
  would be better to have a separate path for create_similar_with_pixel_format() 
  if we need that. But it might be useful for cairo_image_surface_create() ... 
  people are  going to screw up and pass CAIRO_FORMAT_RGB into that, and if it
  "just worked" that would save people trouble....)

* Clean up the API in preparation for freezing and release.

* Make a more interesting PS backend, (other than the current
"giant-image for every page" approach).

* Figure out what to do with DPI for image/png backends.

* Change stroke code to go through one giant polygon. This will fix
problems with stroking self-intersecting paths.

* Re-work the backend clipping interface to use geometry rather than
images.

* Fix the intersection problem, (see reference to Hobby's paper
mentioned in cairo_traps.c).

* Add a new cairo_text_glyphs function (a sort of bridge between the
toy and the real text API):

	>       void
	>       cairo_text_glyphs (cairo_t *cr, const unsigned char *utf8,
	>                          cairo_glyph_t *glyphs, int *num_glyphs);
	>
	> with num_glyphs as an input-output parameter. The behavior of this
	> function would be such that calling:
	>
	>       cairo_text_glyphs (cr, string, glyphs, &num_glyphs);
	>       cairo_show_glyphs (cr, glyphs, num_glyphs);
	>
	> would be equivalent too:
	>
	>       cairo_show_text (cr, string);
	>
	> as long as the original size of glyphs/num_glyphs was large
	> enough.

* Implement dashing for cairo_curve_to.

* Implement support for programmatic patterns, (ie. figure out how to
do gradients the Right Way).

* Implement cairo_arc_to.

* Stroking closed, degenerate paths should still draw caps.  Round
  caps are easy; square should probably draw an axis-aligned square.

* It would be nice if the user had a mechanism to reliably draw custom
  caps. One approach here would be to provide the coordinates of the
  butt cap faces so that the user can append seamless caps to the
  current path. We may also need to provide the coordinates of the
  faces of every dash as well.

* Should add geometry pruning as appropriate.

* We need a way to get at the image data after something
  like cairo_surface_create_similar with the image backend.

* Three suggestions from Owen that will help GTK+ performance:

  - The ability have an additional rectangle-list clip in the
   Xlib surface. Frequently during an expose event, GTK+ is
   drawing L shaped areas

         XXXXXX
         X.....
         X.....

   And passing the real clip to the server is going to save
   a lot of pixel operations that will be thrown away.

 - The ability to pass in a width/height to cairo_xlib_surface_create()
   to avoid a round-trip. (Round-trips are bad to the point where
   querying the the server is something you don't want to do in
   production software)

 - More of a future thing, the ability to hint to to cairo that
   the contents of the Xlib surface passed to
   cairo_xlib_surface_create() are a solid fill ... this is
   very much the normal case for GTK+ usage and allows for
   big optimization in the no-RENDER case.
   (see http://mail.gnome.org/archives/gtk-devel-list/2003-March/msg00045.html

* Verification, profiling, optimization.

	centi_unfinished.svg may provide a good test case.