Add man pages + some minor fixes

Signed-off-by: Mattias Andrée <maandree@kth.se>

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)