Progress Callback
-----------------

The 'gp_progress_cb' is a structure that stores user-defined callback
function and user-defined pointer and percentage.

It is passed as last parameter to functions that would take some time to
complete and adds capability to track the operation progress as well as to
abort the operation.

Currently it's used in link:filters.html[filters] and
link:loaders.html[loaders].

[source,c]
-------------------------------------------------------------------------------
typdedef struct gp_progress_cb {
	float percentage;
	int (*callback)(struct gp_progress_cb *self);
	void *priv;
} gp_progress_cb;
-------------------------------------------------------------------------------

The 'callback' pointer is a pointer to user defined callback function.

The 'priv' pointer can be used to pass a pointer to the callback function and
can accessed inside of the callback by defererencin the 'self' argument.

The 'percentage' field is updated by the function the callback was passed to
and is increased monotonically till it reaches 100.

If 'non-NULL' progress callback structure is passed to a function, it's called
periodically and the percentage field is updated.

The return value from callback could abort the execution. If a non-zero value
is returned operation is aborted, all memory freed etc., in case of pixmap
loaders errno is set to 'ECANCELED' and in case of pixmap savers the newly
created file is removed too.

The callback, if supported, is the last parameter of a function.

TIP: For example usage see progress callback
link:example_loaders_progress_callback.html[example].
