[cairo] API Shakeup: cairo_output_stream_t and cairo_surface_finish()

[Kristian Høgsberg]

Kristian Høgsberg wrote:
> Hi,
> 
> Here is a proposal for an output stream abstraction to be used for
> cairo's output stream needs.  We add a new object, 
> cairo_output_stream_t, to the user API:

And here's a first stab at the implementation.  I decided to go with the
API that keeps the cairo_output_stream_t out of the public API:

   cairo_surface_t *
   cairo_pdf_surface_create (cairo_write_func_t    write_func,
                             cairo_destroy_func_t  destroy_closure_func,
                             void                  *closure,
                             double                width_inches,
                             double                height_inches,
                             double                x_pixels_per_inch,
                             double                y_pixels_per_inch);

   typedef cairo_status_t (*cairo_write_func_t) (const void *data,
                                                 unsigned int length,
                                                 void *closure);
   typedef void (*cairo_destroy_func_t) (void *data);

The write_func is called whenever the backend needs to write data, and 
is passed a pointer to the data, the length of the data and the closure 
argument given to the surface constructor.  When the surface is finished 
eventually, the destroy_closure_func is called with the closure as its 
single argument, to free up resources allocated for the closure.

I've added this stdio convenience function:

   cairo_surface_t *
   cairo_pdf_surface_create_for_file (FILE         *fp,
                                      double       width_inches,
                                      double       height_inches,
                                      double       x_pixels_per_inch,
                                      double       y_pixels_per_inch);

and I added the finish function to the API:

   /**
    * cairo_surface_finish:
    * @surface: the #cairo_surface_t to finish
    *
    * This function finishes the surface and drops all references to
    * external resources.  For example, for the Xlib backend it means
    * that cairo will no longer access the drawable, which can be freed.
    * After calling cairo_surface_finish() the only valid operations on a
    * surface are getting and setting user data and referencing and
    * destroying it.  Further drawing the the surface will not affect the
    * surface but set the surface status to
    * CAIRO_STATUS_SURFACE_FINISHED.
    *
    * When the last call to cairo_surface_destroy() decreases the
    * reference count to zero, cairo will call cairo_surface_finish() if
    * it hasn't been called already, before freeing the resources
    * associated with the surface.
    *
    * Return value: CAIRO_STATUS_SUCCESS if the surface was finished
    * successfully, otherwise CAIRO_STATUS_NO_MEMORY or
    * CAIRO_STATUS_WRITE_ERROR.
    **/
   cairo_status_t
   cairo_surface_finish (cairo_surface_t *surface);

As indicated from the documentation, I've also added two new error 
codes: CAIRO_STATUS_SURFACE_FINISHED which is set if the user tries to 
draw to a closed surface, and CAIRO_STATUS_WRITE_ERROR, which is set if 
a backend fails to write to an output stream.  "Write error" may seem a 
bit too generic, but I don't like the idea of exposing a large number of 
IO error codes either.  The API in this patch should be flexible enough 
though: if you want a simple, easy to use API, use the convenience 
functions (similar to the situation with the toy font API). On the other 
hand, if you care about the specifics of the write failure, use the 
callback API and record the error details in the implementation of the 
write callback.

There is also a convenience function:

   void
   cairo_finish (cairo_t *cr);

which just calls cairo_surface_finish() on the target surface for the 
cairo_t.

In the backend API, I've renamed the destroy surface function to finish. 
  The way it works is that the finish function is required to clean up 
the backend specific parts of the surface, but in contrast to the 
destroy function it doesn't free the memory allocated for the surface. 
After finish has been called for a given surface, the backend is 
guaranteed that it will never see that surface again.

cheers,
Kristian
-------------- next part --------------
A non-text attachment was scrubbed...
Name: output-stream.patch
Type: text/x-patch
Size: 69984 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050221/f2339807/output-stream.bin