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

[Behdad Esfahbod]

On Sat, 2007-12-29 at 21:55 -0500, Behdad Esfahbod wrote:
> 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.

We should do 2 for 1.6.  Any takers?


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