[cairo] How should bindings deal with surfaces of unknown type?

[Behdad Esfahbod]

On Sat, 2007-12-29 at 10:34 -0500, Adrian Johnson wrote:
> Torsten Schoenfeld wrote:
> > On Sun, 2007-10-07 at 15:05 +0200, Torsten Schoenfeld wrote:
> > 
> >> when you cairo_surface_create_similar on, say, a PDF surface, you get a
> >> surface of type CAIRO_INTERNAL_SURFACE_TYPE_META.  But since that's
> >> internal, all you see is a surface of type 4096.  When language bindings
> >> encounter such a surface, they have little choice but to represent it as
> >> a generic surface.  Thus, you can't call PDF specific surface methods on
> >> the result of calling create_similar on a PDF surface.
> > 
> > This problem still persists and I still don't know how to handle it.
> > 
> > How do other bindings deal with this situation?  What do you do with a
> > surface pointer for which cairo_surface_get_type returns an internal and
> > thus unknown value?
> > 
> 
> The current vector surface specific API consists of functions for
> setting the output type (PS Level, SVG Version, enable EPS) and setting
> the page size. I don't think any of these functions makes sense on a
> surface created with cairo_surface_create_similar.
> 
> However it is a bug to expose an internal type. This patch makes the
> meta surface override it's type with the target surface type similar to
> the way the paginated surface works.
> 
> http://gitweb.freedesktop.org/?p=users/ajohnson/cairo.git;a=commit;h=bf4787e0f609091ef57c40ebd580210c51185eac
> 
> With this patch, create similar of a PDF surface will return a surface
> type of PDF. However calling cairo_pdf_surface_set_size() on the similar
> surface will result in CAIRO_STATUS_SURFACE_TYPE_MISMATCH as this
> function only works on the PDF surface created with
> cairo_pdf_surface_create.
> 
> If backend specific API is added that is required to work on similar
> surfaces the new functions will need to store the backend specific
> operations in the meta surface instead of returning a type mismatch.

Currently the Python bindings have the same problem.  There are three
solutions at this time:

  1) Document that create_similar may create private surface types.
Those types should be treated as anonymous subclasses of
cairo_surface_t.  I think all language bindings can easily handle this,
but either making cairo.Surface instantiable or (better?), make a
cairo.UnknownSurface subclass for all those cases.

  2) Make create_similar always return a public surface type.  That is,
PS/PDF/SVG for PS/PDF/SVG.  Then we really have to make sure all the
backend methods work on the returned surface, and work correctly.  One
way would be to make create_similar actually return a real PS/PDF/SVG
surface, one with the file argument NULL, and make file argument NULL
work.  That's probably suboptimal, but should keep things much more
clear and even remove some code.

  3) Make meta-surface public for 1.6.  We can always add methods to it
later.  We just need to fix the constructor right now.  Unfortunately
that's in fact the trickiest part so far.


I tend to prefer 3, 2, 1 in that order.  I also want to see NULL file
argument to PS/PDF/SVG work regardless of this change.

-- 
behdad
http://behdad.org/

"Those who would give up Essential Liberty to purchase a little
 Temporary Safety, deserve neither Liberty nor Safety."
        -- Benjamin Franklin, 1759