From ac7ac58ef6dca8f59f9266a8c0c3bffa8d7ae537 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sat, 23 Apr 2022 12:58:50 +0200 Subject: Documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- libaxl/consts.h | 1 + libaxl/types.h | 2 + man3/LIBAXL_REQUEST_CHANGE_POINTER_CONTROL.3 | 83 ++++++++++++++++ man3/LIBAXL_REQUEST_GET_POINTER_CONTROL.3 | 6 +- man3/LIBAXL_REQUEST_GET_SCREEN_SAVER.3 | 74 ++++++++++++++ man3/LIBAXL_REQUEST_LIST_EXTENSIONS.3 | 69 ++++++++++++++ man3/LIBAXL_REQUEST_SET_SCREEN_SAVER.3 | 138 +++++++++++++++++++++++++++ 7 files changed, 371 insertions(+), 2 deletions(-) create mode 100644 man3/LIBAXL_REQUEST_CHANGE_POINTER_CONTROL.3 create mode 100644 man3/LIBAXL_REQUEST_GET_SCREEN_SAVER.3 create mode 100644 man3/LIBAXL_REQUEST_LIST_EXTENSIONS.3 create mode 100644 man3/LIBAXL_REQUEST_SET_SCREEN_SAVER.3 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 #include +/* 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 + +#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 + +#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 + +#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 + +#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) -- cgit v1.2.3-70-g09d2