| jpayne@68: | |
jpayne@68: |
jpayne@68: |
jpayne@68: |
jpayne@68:
jpayne@68: Like patterns, surfaces, which use only the jpayne@68: cairo_surface_t jpayne@68: type in the C API should be broken up into a hierarchy of types jpayne@68: in a language binding. jpayne@68:
jpayne@68:jpayne@68: cairo_surface_t jpayne@68: cairo_image_surface_t jpayne@68: cairo_atsui_surface_t jpayne@68: cairo_win32_surface_t jpayne@68: cairo_xlib_surface_t jpayne@68: cairo_beos_surface_t jpayne@68:jpayne@68:
jpayne@68: Unlike patterns, the constructors and methods on these types are jpayne@68: clearly named, and can be trivially associated with the jpayne@68: appropriate subtype. Many language bindings will want to avoid jpayne@68: binding the platform-specific subtypes at all, since the jpayne@68: methods on these types are not useful without passing in native jpayne@68: C types. Unless there is a language binding for Xlib available, jpayne@68: there is no way to represent a XLib Display * in jpayne@68: that language. jpayne@68:
jpayne@68:jpayne@68: This doesn't mean that platform-specific surface types can't jpayne@68: be used in a language binding that doesn't bind the constructor. jpayne@68: A very common situation is to use a cairo language binding in jpayne@68: combination with a binding for a higher level system like jpayne@68: the GTK+ widget jpayne@68: toolkit. In such a situation, the higher level toolkit provides jpayne@68: ways to get references to platform specific surfaces. jpayne@68:
jpayne@68:
jpayne@68: The cairo_surface_set_user_data(),
jpayne@68: and cairo_surface_get_user_data()
jpayne@68: methods are provided for use in language bindings, and should
jpayne@68: not be directly exposed to applications. One example of the use
jpayne@68: of these functions in a language binding is creating a binding for:
jpayne@68:
jpayne@68: cairo_surface_t *
jpayne@68: cairo_image_surface_create_for_data (unsigned char *data,
jpayne@68: cairo_format_t format,
jpayne@68: int width,
jpayne@68: int height,
jpayne@68: int stride);
jpayne@68:
jpayne@68:
jpayne@68: The memory block passed in for data must be
jpayne@68: kept around until the surface is destroyed, so the language
jpayne@68: binding must have some way of determining when that happens. The
jpayne@68: way to do this is to use the destroy
jpayne@68: argument to cairo_surface_set_user_data().
jpayne@68:
jpayne@68: Some languages may not have a suitable “pointer to a block of
jpayne@68: data” type to pass in for data. And even
jpayne@68: where a language does have such a type, the user will be
jpayne@68: frequently able to cause the backing store to be reallocated
jpayne@68: to a different location or truncated. Should we recommend a
jpayne@68: standard type name and binding for a buffer object here?
jpayne@68: