Plugin: Abydos: An Image Loading Library

Plugin

Plugin — The API for plugins to use.

Functions

void	(*abydos_plugin_info_func_t) ()
void	(*abydos_plugin_progress_func_t) ()
#define	ABYDOS_PLUGIN_INFO_HAS()
#define	ABYDOS_PLUGIN_PAGE_INFO_HAS()
abydos_plugin_interface_t *	(*abydos_plugin_func_t) ()

Types and Values

	abydos_plugin_handle_t
	abydos_size_t
	abydos_plugin_info_t
#define	ABYDOS_PLUGIN_INFO_VERSION
	abydos_plugin_page_info_t
#define	ABYDOS_PLUGIN_PAGE_INFO_VERSION
	abydos_plugin_interface_t
#define	ABYDOS_PLUGIN_INTERFACE_VERSION

Includes

#include <abydos-plugin.h>

Description

To create a image loading plugin for abydos you must implement a function called "Abydos0" which returns a pointer to an abydos_plugin_interface_t. Which in turn must be filled with points to some functions.

These functions are mandatory:

get_mime_types
new
free

And at least one way to load an image. More than one can be provided. But implementing one by calling another is pointless since abydos knows how to do that anyway. One of these are mandatory:

progressive_begin, progressive_feed and progressive_end
create_from_data
create_from_file

And at least one way to get an image. Both can be provided. But implementing one by calling the other is pointless since abydos knows how to do that anyway. One of these are mandatory:

render
get_image_surface

If the plugin supports variants it also needs to implement:

get_variant_size

If the plugin supports animation it also needs to implement:

get_duration

The rest of the functions are optional.

Functions

abydos_plugin_info_func_t ()

void
(*abydos_plugin_info_func_t) (void *userdata);

The plugin should call this function as soon as the abydos_plugin_info_t is filled.

Parameters

userdata

The userdata passed to progressive_begin (in abydos_plugin_interface_t).

abydos_plugin_progress_func_t ()

void
(*abydos_plugin_progress_func_t) (void *userdata,
                                  cairo_rectangle_int_t *rect);

The plugin should call this function as soon as there is something new that could be rendered.

Parameters

userdata	The userdata passed to `progressive_begin` (in abydos_plugin_interface_t).
rect	An area containing the latest update or NULL.

ABYDOS_PLUGIN_INFO_HAS()

#define ABYDOS_PLUGIN_INFO_HAS(info,member) (offsetof(abydos_plugin_info_t,member)<(info)->version)

Macro to check if the version of the abydos_plugin_info_t info has member .

Parameters

info	Info structure to check.
member	Member to query the existance of.

ABYDOS_PLUGIN_PAGE_INFO_HAS()

#define ABYDOS_PLUGIN_PAGE_INFO_HAS(info,member) (offsetof(abydos_plugin_page_info_t,member)<(info)->version)

Macro to check if the version of the abydos_plugin_page_info_t info has member .

Parameters

info	Page info structure to check.
member	Member to query the existance of.

abydos_plugin_func_t ()

abydos_plugin_interface_t *
(*abydos_plugin_func_t) (void);

Prototype for a function each plugin should export as Abydos0.

Types and Values

abydos_plugin_handle_t

typedef struct _abydos_plugin_handle_t abydos_plugin_handle_t;

A pointer to an object provided by a plugin.

abydos_size_t

typedef struct {
    int width;
    int height;
} abydos_size_t;

Size in pixels.

Members

int `width`;	Width in pixels.
int `height`;	Height in pixels.

abydos_plugin_info_t

typedef struct {
    int version;
    const char *error;
    int width;
    int height;
    double pixel_ratio;
    /* multi page */
    int page_count;
    /* layers */
    int layer_count;
    /* variants */
    int variant_count;
    /* animation */
    int frame_count;
    /* flags */
    cairo_bool_t scalable_size;
    cairo_bool_t scalable_time;
    cairo_bool_t threadsafe;
    /* 0.2 */
    int default_page;
    int default_frame;
    cairo_bool_t threadsafe_render;
} abydos_plugin_info_t;

Info to fill in by a plugin.

Members

int `version`;	Version of the structure. Use ABYDOS_PLUGIN_INFO_HAS to check if a member is available.
const char *`error`;	Error message which can be set by the plugin. If the text is dynamically allocated the plugin must keep track of the message and free it then the plugin handle or the plugin itself is destroyed.
int `width`;	Width of the image in pixels. This must be set by the plugin.
int `height`;	Height of the image in pixels. This must be set by the plugin.
double `pixel_ratio`;	Aspect ratio of a pixel. This can be set by the plugin if it's different from the default of 1.0.
int `page_count`;	Number of pages. This may be set by the plugin if it's different from the default of 1. In that case the plugin may also provide `get_page_info` (in abydos_plugin_interface_t) in case the pages have different characteristics.
int `layer_count`;	Number of layers. This may be set by the plugin if it's different from the default of 1. In that case the plugin may also provide `get_layer_visibility` (in abydos_plugin_interface_t) if some layers could be hidden by default.
int `variant_count`;	Number of variants. This may be set by the plugin if it's different from the default of 1. In that case the plugin must also provide `get_variant_size` (in abydos_plugin_interface_t).
int `frame_count`;	Number of frames. This may be set by the plugin if it's animated and has a discreet number of frames. In that case the plugin may also `get_duration` (in abydos_plugin_interface_t). If the animation doesn't have a descreet number of frames scalable_time can be set.
cairo_bool_t `scalable_size`;	The plugin can set this flag if the render size can be scaled up. Which is typical for vector graphics.
cairo_bool_t `scalable_time`;	The plugin can set this if a frame can be rendered at an arbitrary time (not just discreet frames). Which is typical for vector animation.
cairo_bool_t `threadsafe`;	Completely thread safe. The plugin can set this if all calls are completely thread safe. By default at most one call to the plugin will be made at a time.
int `default_page`;	Can be set by the plugin if some other page than the first page is most representative.
int `default_frame`;	Can be set by the plugin if some other frame than the first frame is most representative.
cairo_bool_t `threadsafe_render`;	At least `render` and `get_image_surface` are thread safe (then available). Can be set by the plugin if the loading function may still be unsafe.

ABYDOS_PLUGIN_INFO_VERSION

#define ABYDOS_PLUGIN_INFO_VERSION sizeof(abydos_plugin_info_t)

The compile time version of abydos_plugin_info_t.

abydos_plugin_page_info_t

typedef struct {
    int version;
    int width;
    int height;
    double pixel_ratio;
    /* layers */
    int layer_count;
    /* variants */
    int variant_count;
    /* animation */
    int frame_count;
    int default_frame;
    /* flags */
    cairo_bool_t scalable_size;
    cairo_bool_t scalable_time;
} abydos_plugin_page_info_t;

Info about a page, to be filled in by a plugin.

Members

int `version`;	Version of the structure. Use ABYDOS_PLUGIN_PAGE_INFO_HAS to check if a member is available.
int `width`;	Width of the page in pixels. Only needs to be set if it differs from the image.
int `height`;	Height of the image in pixels. Only needs to be set if it differs from the image.
double `pixel_ratio`;	Aspect ratio of a pixel. This can be set by the plugin if it's different from the image.
int `layer_count`;	Number of layers. This may be set by the plugin if it's different from the default of 1. In that case the plugin may also provide `get_layer_visibility` (in abydos_plugin_interface_t). if some layers could be hidden by default.
int `variant_count`;	Number of variants. This may be set by the plugin if it's different from the default of 1. In that case the plugin must also provide `get_variant_size` (in abydos_plugin_interface_t).
int `frame_count`;	Number of frames. This may be set by the plugin if it's animated and has a discreet number of frames. In that case the plugin may also provide get_duration` (in abydos_plugin_interface_t). If the animation doesn't have a descreet number of frames scalable_time can be set.
int `default_frame`;	Can be set by the plugin if some other frame than the first frame is most representative.
cairo_bool_t `scalable_size`;	The plugin can set this flag if the render size can be scaled up. Which is typical for vector graphics.
cairo_bool_t `scalable_time`;	The plugin can set this if a frame can be rendered at an arbitrary time (not just discreet frames). Which is typical for vector animation.

ABYDOS_PLUGIN_PAGE_INFO_VERSION

#define ABYDOS_PLUGIN_PAGE_INFO_VERSION sizeof(abydos_plugin_page_info_t)

The compile time version of abydos_plugin_page_info_t.

abydos_plugin_interface_t

typedef struct {
    int version;
    void(*done)(void);
    const char **(*get_mime_types)(void);

    abydos_plugin_handle_t *(*create)(const char *mime_type,abydos_plugin_info_t *);
    void(*destroy)(abydos_plugin_handle_t *);

    void(*progressive_begin)(abydos_plugin_handle_t *,abydos_plugin_info_func_t,abydos_plugin_progress_func_t,void *);
    int(*progressive_feed)(abydos_plugin_handle_t *,const char *data,size_t len);
    int(*progressive_end)(abydos_plugin_handle_t *);
    int (*from_data)(abydos_plugin_handle_t *,const char *data, size_t len);
    int (*from_file)(abydos_plugin_handle_t *,const char *filename);

    void(*render)(abydos_plugin_handle_t *, cairo_t *cr,int page,cairo_bool_t *visible_layers,int prefered_variant,double time,int frame);
    cairo_surface_t *(*get_image_surface)(abydos_plugin_handle_t *,int page,cairo_bool_t *visible_layers,int prefered_variant,double time,int frame);

    void(*get_layer_visibility_OLD)(abydos_plugin_handle_t *,cairo_bool_t *visibility);
    int(*get_variant_size_OLD)(abydos_plugin_handle_t *,abydos_size_t *size);
    void(*get_duration_OLD)(abydos_plugin_handle_t *,double *frame_duration);

    void(*get_page_info)(abydos_plugin_handle_t *, int page, abydos_plugin_page_info_t *);
    void(*get_layer_visibility)(abydos_plugin_handle_t *,int page, cairo_bool_t *visibility);
    void(*get_variant_size)(abydos_plugin_handle_t *,int page, abydos_size_t *size);
    void(*get_duration)(abydos_plugin_handle_t *,int page, double *frame_duration);
} abydos_plugin_interface_t;

Each plugin must provide this function then called through the exported function called Abydos0.

Members

int `version`;	Version of this structure supported by the plugin. Must always be set to `ABYDOS_PLUGIN_INTERFACE_VERSION`.
`done` ()	Function to be called before the plugin is unloaded. (optional)
`get_mime_types` ()	Function to get supported MIME types. If must return a NULL terminated array.
`create` ()	Function to create a new instance of `mime_type` .
`destroy` ()	Function to free all resources associated with the abydos_handle_t. May be called before or after the image has been loaded as well as in the middle of a progressive load.
`progressive_begin` ()	If the plugin implements progressive loading this function will be called before the data stream begins.
`progressive_feed` ()	Called one or more times to progressively feed image data.
`progressive_end` ()	Called after the progressive feed ands.
`from_data` ()	Decode an image from data in memory.
`from_file` ()	Decode an image from a file.
`render` ()	Function to render the image using cairo. The arguments passed to the function has already been checked by abydos and are valid. The arguments `frame` and `time` two ways to express the same thing. Use the one that is most convinient.
`get_image_surface` ()	Function to get an image surface for the image (according to the supplied arguments). Usually just return a reference to an internal image surface created during the load stage.
`get_layer_visibility_OLD` ()	Depricated (only present for ABI compatibility).
`get_variant_size_OLD` ()	Depricated (only present for ABI compatibility).
`get_duration_OLD` ()	Depricated (only present for ABI compatibility).
`get_page_info` ()	If the number of pages is set to more than one and this function is provided it is called for each page to let the plugin set any page specific information.
`get_layer_visibility` ()	If the number of layers is set to more than one and this function is provided it will be called to let the plugin set (the default) visibility for each layer.
`get_variant_size` ()	If the number of variants is set to more than one and this function is provided it will be called to let the plugin specify the size of each variant.
`get_duration` ()	If the number of frames is set to more than one or scalable time is enabled and this function is set it will be called to let the plugin set the duration of each frame.

ABYDOS_PLUGIN_INTERFACE_VERSION

#define ABYDOS_PLUGIN_INTERFACE_VERSION sizeof(abydos_plugin_interface_t)

The compile time version of abydos_plugin_interface_t.