diff options
Diffstat (limited to 'libglitter_enable_acceleration.3')
| -rw-r--r-- | libglitter_enable_acceleration.3 | 113 |
1 files changed, 113 insertions, 0 deletions
diff --git a/libglitter_enable_acceleration.3 b/libglitter_enable_acceleration.3 new file mode 100644 index 0000000..3f3f833 --- /dev/null +++ b/libglitter_enable_acceleration.3 @@ -0,0 +1,113 @@ +.TH LIBGLITTER_ENABLE_ACCELERATION 3 LIBGLITTER +.SH NAME +libglitter_enable_acceleration - Enable hardware acceleration +.SH SYNOPSIS +.LP +.nf +#include <libglitter.h> + +int libglitter_enable_acceleration(uint64_t \fIfeatures\fP, int \fIasync\fP, + void (*\fIcallback\fP)(int, int, void *), + void *\fIuserdata\fP, void *\fIunused\fP); +.fi +.PP +Link with +.IR "-lglitter" . +.SH DESCRIPTION +The +.BR libglitter_enable_acceleration () +function is planned to in the future enable hardware +acceleration. Because it can be expansive to enable hardware +acceleration (such as compiling code for the acceleration +hardware (normally a graphics card)), and depending on the +use case, it could also be too expensive to issue commands +to the acceleration hardware, (1) hardware acceleration +is not enabled by default, and (2) it can be enabled +asynchronous, meaning that the applications can use the +CPU implementations of the libraries functions at the +beginning of its runtime and enable hardware acceleration +in the background, and once it has been enabled, the +library will shift over to using the hardware acceleration. +.PP +The +.I features +parameter is used to specify which functions to enable +hardware acceleration for. Recognised values are documented +separately, in the documentation for the affected functions. +Any unsupported bit, or combination, is silently ignored. +.PP +To enable hardware acceleration asynchronously, specify a +non-zero value as the +.I async +argument. To enable hardware acceleration synchronously +(meaning that the function does not return until either +hardware acceleration has been enabled or failed to be +enabled), specify zero as the +.I async +argument. +.PP +Unless +.I callback +is +.IR NULL , +the function will call +.I *callback +immedately before it or the thread it spawns terminates. +The first argument will be set to the value the function +would return if +.I async +was 0, and the second argument will be set to the value +the function will set +.I errno +to if +.I async +was 0 (note that the function call still set +.I errno +if it returns a negative value even if +.I async +is not 0). The third argument will be +.IR userdata . +.PP +The +.I userdata +argument not used except for being passed into +.IR *callback . +.PP +The +.I unused +parameter is reserved for future use, +.I NULL +must be specified at the moment. +.SH RETURN VALUES +The +.BR libglitter_enable_acceleration () +function returns the value 1 if it completes successfully +with hardware acceleration enabled, the value 0 if it +completes successfully without hardware acceleration enabled +(this is what will usually happen if +.I async +is set to a non-zero value, but another value may still be +provided as the first argument to +.IR *callback ), +and a negative value on failure. The value -1 is reserved +for when the function sets +.I errno +to specify the error. Other negative values may be used +in the future to specify errors that do not have a good +.I errno +value. +.SH ERRORS +Currently none. +.SH FUTURE DIRECTIONS +The +.BR libglitter_enable_acceleration () +function, once properly implemented, will require additional +linking flags, including (probably) +.I -pthread +(for asynchronous operation) and linking to libraries needed +to use hardware acceleration. +.SH SEE ALSO +.BR libglitter (7), +.BR libglitter_colour_model_convert_rasters_double (3), +.BR libglitter_compose_double (3), +.BR libglitter_desaturate_double (3) |