[cairo] surfaces and backends

[Behdad Esfahbod]

On Fri, 24 Feb 2006, Carl Worth wrote:

> On Fri, 24 Feb 2006 14:59:06 -0500 (EST), Behdad Esfahbod wrote:
> >
> > I don't like the hardcoding of backend-specific stuff in cairo.h.
> > cairo does not export enough internals to allow implementing a
> > backend out of tree I guess, but still I find the following
> > approach more flexible:
> >
> > typedef const char *CairoTypeID;
> >
> > CairoTypeID cairo_surface_get_type (cairo_surface_t *surface);
>
> Hmm... I went to implement this and found it really hard to
> document. There's no available list to point at in the documentation
> for what values can be expected to be returned by the function. The
> destruction of the central list is the point of the approach, but it's
> quite a defect when it comes to the documentation.
>
> So, if we have to put the central list into the documentation, (I
> can't come up with any alternative really), why don't we just put the
> enum in cairo.h too?

You don't need to list them in documentation either.  Something
like this:

/* cairo_surface_get_type:
 * Returns a unique type identifier for the surface.  You can
 * check whether the surface is of a certain kind, by checking
 * this id against the respective identifier acquired by
 * backend-specific type identifiers, e.g. cairo_image_surface_type.
 */

Not listing all available types is a feature, not a bug.  Better
yet, make it like this:

typdef struct _cairo_type_id *CairoTypeID;

const CairoTypeID cairo_surface_get_type (.);

and have a:

const char *cairo_type_id_to_string (CairoTypeID id);

The implementation of which of course simply returns (const char *) id
for now, but CariTypeID's implementation can be extended in the
future, to a real Type struct, for example, to keep status, ref
count, and some other "object" info...

If going this way, one can define is_of_type macros in
backend-specific headers too...

> As for out-of-tree backends, we can extend this type advertising as
> needed when we allow those in the future.
>
> -Carl
>

--behdad
http://behdad.org/

"Commandment Three says Do Not Kill, Amendment Two says Blood Will Spill"
	-- Dan Bern, "New American Language"