Script Surfaces

Script Surfaces — Rendering to replayable scripts

Synopsis

#define             CAIRO_HAS_SCRIPT_SURFACE
cairo_device_t *    cairo_script_create                 (const char *filename);
cairo_device_t *    cairo_script_create_for_stream      (cairo_write_func_t write_func,
                                                         void *closure);
cairo_status_t      cairo_script_from_recording_surface (cairo_device_t *script,
                                                         cairo_surface_t *recording_surface);
cairo_script_mode_t cairo_script_get_mode               (cairo_device_t *script);
enum                cairo_script_mode_t;
void                cairo_script_set_mode               (cairo_device_t *script,
                                                         cairo_script_mode_t mode);
cairo_surface_t *   cairo_script_surface_create         (cairo_device_t *script,
                                                         cairo_content_t content,
                                                         double width,
                                                         double height);
cairo_surface_t *   cairo_script_surface_create_for_target
                                                        (cairo_device_t *script,
                                                         cairo_surface_t *target);
void                cairo_script_write_comment          (cairo_device_t *script,
                                                         const char *comment,
                                                         int len);

Description

The script surface provides the ability to render to a native script that matches the cairo drawing model. The scripts can be replayed using tools under the util/cairo-script directoriy, or with cairo-perf-trace.

Details

CAIRO_HAS_SCRIPT_SURFACE

#define CAIRO_HAS_SCRIPT_SURFACE 1

Defined if the script surface backend is available. The script surface backend is always built in since 1.12.

Since 1.12

cairo_script_create ()

cairo_device_t *    cairo_script_create                 (const char *filename);

Creates a output device for emitting the script, used when creating the individual surfaces.

filename :

 the name (path) of the file to write the script to

Returns :

 a pointer to the newly created device. The caller owns the surface and should call cairo_device_destroy() when done with it. This function always returns a valid pointer, but it will return a pointer to a "nil" device if an error such as out of memory occurs. You can use cairo_device_status() to check for this.

Since 1.12

cairo_script_create_for_stream ()

cairo_device_t *    cairo_script_create_for_stream      (cairo_write_func_t write_func,
                                                         void *closure);

Creates a output device for emitting the script, used when creating the individual surfaces.

write_func :

 callback function passed the bytes written to the script

closure :

 user data to be passed to the callback

Returns :

 a pointer to the newly created device. The caller owns the surface and should call cairo_device_destroy() when done with it. This function always returns a valid pointer, but it will return a pointer to a "nil" device if an error such as out of memory occurs. You can use cairo_device_status() to check for this.

Since 1.12

cairo_script_from_recording_surface ()

cairo_status_t      cairo_script_from_recording_surface (cairo_device_t *script,
                                                         cairo_surface_t *recording_surface);

Converts the record operations in recording_surface into a script.

script :

 the script (output device)

recording_surface :

 the recording surface to replay

Returns :

 CAIRO_STATUS_SUCCESS on successful completion or an error code.

Since 1.12

cairo_script_get_mode ()

cairo_script_mode_t cairo_script_get_mode               (cairo_device_t *script);

Queries the script for its current output mode.

script :

 The script (output device) to query

Returns :

 the current output mode of the script

Since 1.12

enum cairo_script_mode_t

typedef enum {
    CAIRO_SCRIPT_MODE_ASCII,
    CAIRO_SCRIPT_MODE_BINARY
} cairo_script_mode_t;

A set of script output variants.

CAIRO_SCRIPT_MODE_ASCII

 the output will be in readable text (default). (Since 1.12)

CAIRO_SCRIPT_MODE_BINARY

 the output will use byte codes. (Since 1.12)

Since 1.12

cairo_script_set_mode ()

void                cairo_script_set_mode               (cairo_device_t *script,
                                                         cairo_script_mode_t mode);

Change the output mode of the script

script :

 The script (output device)

mode :

 the new mode

Since 1.12

cairo_script_surface_create ()

cairo_surface_t *   cairo_script_surface_create         (cairo_device_t *script,
                                                         cairo_content_t content,
                                                         double width,
                                                         double height);

Create a new surface that will emit its rendering through script

script :

 the script (output device)

content :

 the content of the surface

width :

 width in pixels

height :

 height in pixels

Returns :

 a pointer to the newly created surface. The caller owns the surface and should call cairo_surface_destroy() when done with it. This function always returns a valid pointer, but it will return a pointer to a "nil" surface if an error such as out of memory occurs. You can use cairo_surface_status() to check for this.

Since 1.12

cairo_script_surface_create_for_target ()

cairo_surface_t *   cairo_script_surface_create_for_target
                                                        (cairo_device_t *script,
                                                         cairo_surface_t *target);

Create a pxoy surface that will render to target and record the operations to device.

script :

 the script (output device)

target :

 a target surface to wrap

Returns :

 a pointer to the newly created surface. The caller owns the surface and should call cairo_surface_destroy() when done with it. This function always returns a valid pointer, but it will return a pointer to a "nil" surface if an error such as out of memory occurs. You can use cairo_surface_status() to check for this.

Since 1.12

cairo_script_write_comment ()

void                cairo_script_write_comment          (cairo_device_t *script,
                                                         const char *comment,
                                                         int len);

Emit a string verbatim into the script.

script :

 the script (output device)

comment :

 the string to emit

len :

 the length of the sting to write, or -1 to use strlen()

Since 1.12

See Also

cairo_surface_t
Generated by GTK-Doc V1.18