[cairo] Creating new Backend

[Carl Worth]

On Mon, 8 May 2006 12:38:36 +0200, Wolfgang Draxinger wrote:
> Simple question:
> 
> What's the best starting point for implementing own backends?

I think it depends on what you're wanting to do, so I'll sketch out
two possibilities for use cases below. For each one I'll recommend a
source file to be used as the starting point, (something minimal that
can be directly copied to start with, then built up incrementally), as
well as some more complete examples for reference.

[I'm guessing the raster/display case below is the one you're
interested in, but I'll describe both just for completeness.]

1) Vector/paginated backend

	This would be for something along the lines of the SVG,
	PostScript, or PDF backends in which there is support for
	multiple pages of output, and it is acceptable for drawing
	operations to be queued up for each page and analyzed for
	fallbacks before the actual backend ever sees anything.

	In this case, the recommend starting-point file is:

		test-paginated-surface.c

	And some more complete examples are:

		cairo-pdf-surface.c
		cairo-ps-surface.c
		cairo-svg-surface.c

	where a lot of the complexity comes in font subsetting, (which
	I hope to start generalizing and pushing out into common
	files---much like cairo-font-subset.c which exists but has no
	current users other than cairo-pdf-surface.c).

2) Raster/display backend

	This would be for something that is targeting a display
	device that expects immediate results, and it is reasonable to
	expect that a rasterized version of the surface will
	faithfully capture its contents.

	In this case, the recommended starting-point file is:

		test-fallback-surface.c

	And as more complete examples you can look at basically any of
	the other existing surfaces, (image, xlib, glitz, quartz,
	directfb, beos).

The big advantage of using the test surfaces I mention above as
starting points is that they both do a good job of implementing as few
functions as possible in the surface backend interface while still
being "complete".

And it's worth noting that other than the get_extents function, the
sets of functions that these two surfaces implement are entirely
disjoint. That does suggest that we might want to split this backend
interface up into two corresponding sets of functions, (let's call
these the high-level and the low-level functions for now).

The two test surfaces are both backed by an image surface. In the case
of test-paginated surface it implements all of the high-level
functions in the backend interface, (eg. paint, mask, stroke, fill,
show_glyphs, and the (misfit) set_clip_region). This is the minimal
set of functions necessary to guarantee that the backend will never be
required to provide or accept a rasterized version of its content,
(through the low-level acquire_source/dest_image), which these kinds
of backends may not be capable of doing at all.

On the other hand, the test-fallback-surface implements a minimal set
of functions from the opposite end, (the low-level functions). By
implementing both sets of acquire/release functions, the surface
fallback code, (cairo-surface-fallback.c), is able to provide
image-surface renderings of all operations.

Incremental improvement of the test-fallback surface would consist of
progressively implementing higher-level functions as
convenient/appropriate for the particular backend so that the
acquire/release fallback paths are used less frequently.

Incrementally improving the test-paginated surface is a slightly more
involved process. It's not likely to be necessary to implement more
functions. Instead, the analysis phase is currently indicating that
all functions are supported, (always returning CAIRO_STATUS_SUCCESS
when paginated_mode is CAIRO_PAGINATED_MODE_ANALYZE). To make this
"real" the first thing to do would be to change all of these to return
CAIRO_INT_STATUS_UNSUPPORTED, then provide an implementation of the
paint function that was capable of accepting the
image-fallback-rendered result of the entire page. After that,
individual operations could be conditionally supported and also
changed to report SUCCESS during the analysis phase.

Finally, the analysis is currently limited to doing fallbacks or not
at the page-level only, though this is expected to change in the
future.

-Carl

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20060508/9d23385d/attachment.pgp