Documentation

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

7 files changed, 371 insertions, 2 deletions

diff --git a/libaxl/consts.h b/libaxl/consts.h
index ac9e43b..b4e9b76 100644
--- a/libaxl/consts.h
+++ b/libaxl/consts.h
@@ -272,6 +272,7 @@
 #define LIBAXL_COPY_FROM_PARENT     0
 #define LIBAXL_POINTER_ROOT         1
 #define LIBAXL_PARENT               2
+#define LIBAXL_RESTORE_DEFAULT     -1
 
 /* window event mask */
 #define LIBAXL_EVENT_MASK_KEY_PRESS             UINT32_C(0x00000001) /* in SETofDEVICEEVENT                       */
diff --git a/libaxl/types.h b/libaxl/types.h
index 0ece759..f528f42 100644
--- a/libaxl/types.h
+++ b/libaxl/types.h
@@ -7,6 +7,8 @@
 #include <stddef.h>
 #include <stdint.h>
 
+/* TODO man(makefile) */
+
 typedef uint32_t    libaxl_id_t;
 typedef libaxl_id_t libaxl_window_t;
 typedef libaxl_id_t libaxl_pixmap_t;
diff --git a/man3/LIBAXL_REQUEST_CHANGE_POINTER_CONTROL.3 b/man3/LIBAXL_REQUEST_CHANGE_POINTER_CONTROL.3
new file mode 100644
index 0000000..02598ed
--- /dev/null
+++ b/man3/LIBAXL_REQUEST_CHANGE_POINTER_CONTROL.3
@@ -0,0 +1,83 @@
+.TH LIBAXL_REQUEST_CHANGE_POINTER_CONTROL 3 libaxl
+.SH NAME
+LIBAXL_REQUEST_CHANGE_POINTER_CONTROL - Set acceleration or threshold for the pointer
+.SH SYNOPSIS
+.nf
+#include <libaxl.h>
+
+#define LIBAXL_REQUEST_CHANGE_POINTER_CONTROL 105
+struct libaxl_request_change_pointer_control {
+        uint8_t       \fIopcode\fP;
+        uint8_t       \fI__pad\fP;
+        uint16_t      \fI_request_length\fP;
+        int16_t       \fIacceleration_numerator\fP;
+        int16_t       \fIacceleration_denominator\fP;
+        int16_t       \fIthreshold\fP;
+	libaxl_bool_t \fIdo_acceleration\fP;
+	libaxl_bool_t \fIdo_threshold\fP;
+};
+.fi
+.SH DESCRIPTION
+The display server shall reconfigure the
+acceleration, if the
+.I do_acceleration
+field is set to
+.IR LIBAXL_TRUE ,
+and the threshold, if the
+.I do_threshold
+field is set to
+.IR LIBAXL_TRUE ,
+for the pointer; the display server may however
+round the accerlation arbitrarily.
+.PP
+The
+.I acceleration_numerator
+and
+.I acceleration_denominator
+fields shall be set so that
+.I ((double)acceleration_numerator/acceleration_denominator)
+is the desired multiple of the normal acceleration that
+shall be set to the acceleration of the pointer.
+.PP
+The
+.I threshold
+field shall be set to the desired threshold for the pointer,
+that is, the number of the pixels the pointer must move at
+once before acceleration takes place (acceleration only
+applies to the pixels beyond the threshold).
+.PP
+Setting one these fields to
+.I LIBAXL_RESTORE_DEFAULT
+(=
+.IR -1 )
+restores the default value.
+.PP
+The value of the
+.I opcode
+field shall be
+.I LIBAXL_REQUEST_CHANGE_POINTER_CONTROL
+to signify that the request is of the
+request described in this document.
+.PP
+Other fields are filled in automatically by the
+.BR libaxl_send_request (3)
+function.
+.SH ERRORS
+.TP
+.BR LIBAXL_ERROR_VALUE (3)
+.IR acceleration_numerator ,
+.IR acceleration_denominator ,
+or
+.IR threshold ,
+is less than
+.I -1
+or
+.I acceleration_denominator
+is
+.IR 0 .
+.SH REPLIES
+None.
+.SH
+.BR libaxl_send_request (3),
+.BR libaxl_receive (3),
+.BR LIBAXL_REQUEST_GET_POINTER_CONTROL (3)
diff --git a/man3/LIBAXL_REQUEST_GET_POINTER_CONTROL.3 b/man3/LIBAXL_REQUEST_GET_POINTER_CONTROL.3
index 9cc6f37..855f51a 100644
--- a/man3/LIBAXL_REQUEST_GET_POINTER_CONTROL.3
+++ b/man3/LIBAXL_REQUEST_GET_POINTER_CONTROL.3
@@ -42,7 +42,6 @@ struct libaxl_reply_get_pointer_control {
 };
 .fi
 .PP
-.PP
 The display server shall, unless it returns an
 error, return one
 .B "struct libaxl_reply_get_pointer_control"
@@ -55,7 +54,10 @@ fields set such that
 is the value of the current acceleration for the pointer,
 and the
 .I threshold
-field set to the current threshold for the pointer.
+field set to the current threshold for the pointer, that is,
+the number of pixels the pointer must move at once before
+acceleration takes affect (acceleration only applies to the
+pixels beyond the threshold).
 .SH
 .BR libaxl_send_request (3),
 .BR libaxl_receive (3),
diff --git a/man3/LIBAXL_REQUEST_GET_SCREEN_SAVER.3 b/man3/LIBAXL_REQUEST_GET_SCREEN_SAVER.3
new file mode 100644
index 0000000..03fff92
--- /dev/null
+++ b/man3/LIBAXL_REQUEST_GET_SCREEN_SAVER.3
@@ -0,0 +1,74 @@
+.TH LIBAXL_REQUEST_GET_SCREEN_SAVER 3 libaxl
+.SH NAME
+LIBAXL_REQUEST_GET_SCREEN_SAVER - Get screen-saver configurations
+.SH SYNOPSIS
+.nf
+#include <libaxl.h>
+
+#define LIBAXL_REQUEST_GET_GCREEN_SAVER 108
+struct libaxl_request_get_screen_saver {
+        uint8_t  \fIopcode\fP;
+        uint8_t  \fI__pad1\fP;
+        uint16_t \fI_request_length\fP;
+};
+.fi
+.SH DESCRIPTION
+Requests the current screen-saver configurations
+from the display server.
+.PP
+The value of the
+.I opcode
+field shall be
+.I LIBAXL_REQUEST_GET_SCREEN_SAVER
+to signify that the request is of the
+request described in this document.
+.PP
+Other fields are filled in automatically by the
+.BR libaxl_send_request (3)
+function.
+.SH ERRORS
+None.
+.SH REPLIES
+.nf
+struct libaxl_reply_get_screen_saver {
+        uint8_t  \fI__one\fP;
+        uint8_t  \fI__pad\fP;
+        uint16_t \fIsequence_number\fP;
+        uint32_t \fI_reply_length\fP;
+        uint16_t \fItimeout\fP;
+        uint16_t \fIinterval\fP;
+        uint8_t  \fIprefer_blanking\fP;
+        uint8_t  \fIallow_exposures\fP;
+        uint8_t  \fI__unused\fP[18];
+};
+.fi
+.PP
+The display server shall, unless it returns an
+error, return one
+.B "struct libaxl_reply_get_screen_saver"
+with the
+.I timeout
+field set to the screen-saver timeout, in seconds, or
+.I LIBAXL_DISABLED
+if disabled, the
+.I interval
+field set to the screen-saver's periodic-change
+interval, in seconds, or
+.I LIBAXL_DISABLED
+if disabled, the
+.I prefer_blanking
+and
+.I allow_exposures
+fields set to either
+.I LIBAXL_YES
+or
+.IR LIBAXL_NO ,
+depending on whether monitor blanking is preferred
+an whether exposure events are allowed, respectively.
+For more information refer to
+.BR LIBAXL_REQUEST_SET_SCREEN_SAVER (3).
+.SH SEE ALSO
+.BR libaxl_send_request (3),
+.BR libaxl_receive (3),
+.BR LIBAXL_REQUEST_SET_SCREEN_SAVER (3),
+.BR LIBAXL_REQUEST_FORCE_SCREEN_SAVER (3)
diff --git a/man3/LIBAXL_REQUEST_LIST_EXTENSIONS.3 b/man3/LIBAXL_REQUEST_LIST_EXTENSIONS.3
new file mode 100644
index 0000000..401775e
--- /dev/null
+++ b/man3/LIBAXL_REQUEST_LIST_EXTENSIONS.3
@@ -0,0 +1,69 @@
+.TH LIBAXL_REQUEST_LIST_EXTENSIONS 3 libaxl
+.SH NAME
+LIBAXL_REQUEST_LIST_EXTENSIONS - Get support display server protocol extension
+.SH SYNOPSIS
+.nf
+#include <libaxl.h>
+
+#define LIBAXL_REQUEST_LIST_EXTENSIONS 99
+struct libaxl_request_list_extensions {
+        uint8_t  \fIopcode\fP;
+        uint8_t  \fI__pad1\fP;
+        uint16_t \fI_request_length\fP;
+};
+.fi
+.SH DESCRIPTION
+Requests the a list of protocol extensions supported
+by the display server
+.PP
+The value of the
+.I opcode
+field shall be
+.I LIBAXL_REQUEST_LIST_EXTENSIONS
+to signify that the request is of the
+request described in this document.
+.PP
+Other fields are filled in automatically by the
+.BR libaxl_send_request (3)
+function.
+.SH ERRORS
+None.
+.SH REPLIES
+.nf
+struct libaxl_reply_list_extensions {
+        uint8_t             \fI__one\fP;
+        uint8_t             \fInumber_of_names\fP;
+        uint16_t            \fIsequence_number\fP;
+        uint32_t            \fI_reply_length\fP;
+        uint8_t             \fI__unused\fP[24];
+        struct libaxl_str8 *\fInames\fP;
+};
+
+struct libaxl_str8 {
+        uint8_t \fIlength\fP;
+        char   *\fIname\fP;
+};
+.fi
+.PP
+The display server shall, unless it returns an
+error, return one
+.B "struct libaxl_reply_list_extensions"
+with the
+.I number_of_names
+field set to the number of support extensions,
+and with their names stored in
+.IR names ,
+where
+.IR names[i].length ,
+for indices
+.I i
+in [
+.IR 0 ,
+.IR number_of_names ),
+is the length of
+.IR names[i].name ,
+which is the name of a supported extension.
+.SH SEE ALSO
+.BR libaxl_send_request (3),
+.BR libaxl_receive (3),
+.BR LIBAXL_REQUEST_QUERY_EXTENSION (3)
diff --git a/man3/LIBAXL_REQUEST_SET_SCREEN_SAVER.3 b/man3/LIBAXL_REQUEST_SET_SCREEN_SAVER.3
new file mode 100644
index 0000000..c483a84
--- /dev/null
+++ b/man3/LIBAXL_REQUEST_SET_SCREEN_SAVER.3
@@ -0,0 +1,138 @@
+.TH LIBAXL_REQUEST_SET_SCREEN_SAVER 3 libaxl
+.SH NAME
+LIBAXL_REQUEST_SET_SCREEN_SAVER - Configure screen-saver
+.SH SYNOPSIS
+.nf
+#include <libaxl.h>
+
+#define LIBAXL_REQUEST_SET_SCREEN_SAVER 107
+struct libaxl_request_set_screen_saver {
+        uint8_t  \fIopcode\fP;
+        uint8_t  \fI__pad1\fP;
+        uint16_t \fI_request_length\fP;
+        int16_t  \fItimeout\fP;
+        int16_t  \fIinterval\fP;
+        uint8_t  \fIprefer_blanking\fP;
+        uint8_t  \fIallow_exposures\fP;
+        uint8_t  \fI__pad2\fP;
+};
+.fi
+.SH DESCRIPTION
+If the
+.I timeout
+field is set to
+.I LIBAXL_DISABLE
+(=
+.IR 0 ),
+the display server shall disable screen-saving,
+but shall however not deactivate any currently
+active screen saver.
+.PP
+If the
+.I timeout
+field is set to a positive value, the display
+server shall enable screen-saving and start the
+screen saver whenever there has been no human
+input to the display server (for example keyboard
+or pointer input) for
+.I timeout
+seconds.
+.PP
+If the
+.I timeout
+field is set to
+.I LIBAXL_RESTORE_DEFAULT
+(=
+.IR -1 ),
+the default value for this field is applied.
+.PP
+If the
+.I prefer_blanking
+field is set to
+.I LIBAXL_YES
+or is set to
+.I LIBAXL_DEFAULT
+and the default value is
+.IR LIBAXL_YES ,
+when the screen-saver is activated, any monitor
+than supports video blanking will go blank.
+.PP
+If the
+.I allow_exposures
+field is set to
+.I LIBAXL_YES
+or is set to
+.I LIBAXL_DEFAULT
+and the default value is
+.IR LIBAXL_YES ,
+or if the screen can be regenerated without sending
+exposure events to the clients, when the screen-saver
+is activated, any monitor that is not blanked is
+changed in a server-dependent fashion to avoid
+burn-in/burn-out. Otherwise, any monitor that is not
+blanked when the screen-saver is activated will remain
+unchanged.
+.PP
+If the screen saver is subject to periodic changes
+(for example by periodically changing the colour map),
+the value of the
+.I interval
+field serves as a hint to the display server how often
+it shall change. This is expressed as an interval in
+seconds. If the
+.I interval
+field is set to
+.I LIBAXL_DISABLE
+(=
+.IR 0 ),
+periodic change is disabled.
+.PP
+If the
+.I interval
+field is set to
+.I LIBAXL_RESTORE_DEFAULT
+(=
+.IR -1 ),
+the default value for this field is applied.
+.PP
+The value of the
+.I opcode
+field shall be
+.I LIBAXL_REQUEST_SET_SCREEN_SAVER
+to signify that the request is of the
+request described in this document.
+.PP
+Other fields are filled in automatically by the
+.BR libaxl_send_request (3)
+function.
+.SH ERRORS
+.TP
+.BR LIBAXL_ERROR_VALUE (3)
+.I timeout
+or
+.I interval
+is less than
+.I -1
+or
+.I prefer_blanking
+or
+.I allow_exposures
+is neither
+.IR LIBAXL_NO ,
+.IR LIBAXL_YES ,
+nor
+.IR LIBAXL_DEFAULT .
+.SH REPLIES
+None.
+.SH NOTES
+The screen-saver is deactivated when there is
+human input or when there is a
+.BR LIBAXL_REQUEST_FORCE_SCREEN_SAVER (3)
+request made with the
+.I mode
+set to
+.IR LIBAXL_RESET .
+.SH SEE ALSO
+.BR libaxl_send_request (3),
+.BR LIBAXL_REQUEST_GET_SCREEN_SAVER (3),
+.BR LIBAXL_REQUEST_FORCE_SCREEN_SAVER (3)