## Script Surfaces

Script Surfaces — Rendering to replayable scripts

## Functions

cairo_device_t * | cairo_script_create ()
cairo_device_t * | cairo_script_create_for_stream ()
cairo_status_t | cairo_script_from_recording_surface ()
cairo_script_mode_t | cairo_script_get_mode ()
void | cairo_script_set_mode ()
cairo_surface_t * | cairo_script_surface_create ()
cairo_surface_t * | cairo_script_surface_create_for_target ()
void | cairo_script_write_comment ()

## Types and Values

#define | CAIRO_HAS_SCRIPT_SURFACE
enum | cairo_script_mode_t

## Object Hierarchy

## 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 directory, or with cairo-perf-trace.

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

script | The script (output device) to query |

#### Returns

the current output mode of the script

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

#### Parameters

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`

#### Parameters

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

#### Parameters

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.

#### Parameters

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

## Types and Values

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

### enum cairo_script_mode_t

A set of script output variants.

#### Members

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

## See Also

cairo_surface_t