cairo/TODO

Changes that are expected to impact the public API
==================================================

 Patch submitted to mailing list?
/ Documentation included in patch?
|/ Review of patch completed?
||/ Test case included?
|||/ Committed.
||||/
Backwards compatible (API additions only)
-----------------------------------------
	cairo_begin_group, cairo_end_group, cairo_get_group
	cairo_surface_mark_dirty (see below for details)
	Add support for non-antialiased rendering. API ?
	Add CAIRO_FILL_RULE_INVERSE_WINDING and CAIRO_FILL_RULE_INVERSE_EVEN_ODD
	Add cairo_text_glyphs (see below for details)
	Add support for programmatic patterns, (ie. arbitrary gradients)
	Add cairo_arc_to.
	Add support for custom caps (see below for details)
	Add support for getting at image data from image surface
	Add CAIRO_STATUS_DESTROYED
	Add cairo_finish

Backwards incompatible (API deletions or changes)
-------------------------------------------------
PDR C	cairo_surface_finish, cairo_surface_flush
PDR C	A hidden offset for the xlib backend
P	Consistent error handling for all objects
	Split cairo_format_t (see below for details)
P---C	Remove cairo_status_string in favor of cairo_status_to_string

Details on some of the above changes
------------------------------------
* cairo_surface_mark_dirty

  One question is what the function should accept. A single
  device-space rectangle seems like a consistent approach. That would
  allow us to avoid needing backend-specific functions with
  backend-specific region datatypes, (cf. clipping support)

  In order to get the intended efficiency benefits, we'll need to make
  two changes:

	1) In the fallback code, never fetch any data from the clean
           region.

	2) Mark clean any region drawn with device-pixel aligned
           rectangles, (cairo_paint with no clip is the most iportant
           one here).

* cairo_text_glyphs:

	It would function as a sort of bridge between the toy and the
	real text APIs:

	>       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.

* support for custom caps:

  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.

* 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....)

Changes that do not affect the public API
=========================================
* Clean up the cache code a bit, (there is at least one redundant
  level of cacheing, and there are some minor style issues).

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

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

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

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

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

* Implement dashing for cairo_curve_to.

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

* Should add geometry pruning as appropriate.

* Verification, profiling, optimization.

	centi_unfinished.svg may provide a good test case.