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