From 23319105a47bcfac33a6f834e6b599e2ccf9849c Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Mon, 18 Jul 2016 18:01:03 +0200 Subject: Document macros, enums, structs, and unions in libcoopgamma.h.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- README | 3 +- doc/man/libcoopgamma.7 | 4 +- doc/man/libcoopgamma.h.0 | 388 +++++++++++++++++++++++++++++++++++++++++++++++ src/libcoopgamma.h | 139 +++++++++-------- 4 files changed, 462 insertions(+), 72 deletions(-) create mode 100644 doc/man/libcoopgamma.h.0 diff --git a/README b/README index 1c27820..53dd625 100644 --- a/README +++ b/README @@ -27,4 +27,5 @@ RATIONALE user friendly. SEE ALSO - coopgammad(1), gc-tools(7) + libcoopgamma.h(0), coopgammad(1), gc-tools(7), + libclut(7) diff --git a/doc/man/libcoopgamma.7 b/doc/man/libcoopgamma.7 index 3ddfd81..8955cdf 100644 --- a/doc/man/libcoopgamma.7 +++ b/doc/man/libcoopgamma.7 @@ -30,5 +30,7 @@ whichever comes first. .SH "RATIONALE" One program cannot do everything and still be user friendly. .SH "SEE ALSO" +.BR libcoopgamma.h (0), .BR coopgammad (1), -.BR gc-tools (7). +.BR gc-tools (7), +.BR libclut (7) diff --git a/doc/man/libcoopgamma.h.0 b/doc/man/libcoopgamma.h.0 new file mode 100644 index 0000000..2350d2f --- /dev/null +++ b/doc/man/libcoopgamma.h.0 @@ -0,0 +1,388 @@ +.TH LIBCOOPGAMMA 7 LIBCOOPGAMMA +.SH "NAME" +libcoopgamma.h - Cooperative gamma library header +.SH "SYNOPSIS" +.nf +#include +.fi +.SH "DESCRIPTION" +The +.B +header includes the +.BR , +.BR , +and +.BR +headers. +.P +The +.B +header defines the macros which expands to integer +constant expressions with distinct values: +.TP +.BR LIBCOOPGAMMA_SUCCESS " = 0" +Unmarshal was successful. +.TP +.BR LIBCOOPGAMMA_INCOMPATIBLE_DOWNGRADE " > 0" +Unmarshal failed. The marshalled data was created +with a older version of libcoopgamma that does not +marshall the data in a compatible way. +.TP +.BR LIBCOOPGAMMA_INCOMPATIBLE_UPGRADE " > 0" +Unmarshal failed. The marshalled data was created with +a newer version libcoopgamma that does not marshall +the data in a compatible way. +.TP +.BR LIBCOOPGAMMA_ERRNO_SET " < 0 (-1)" +Unmarshal failed because of an error, +.I errno +has been set appropriately. +.P +The +.B +header defines +.I "enum libcoopgamma_support" +with the alias +.I libcoopgamma_support_t +and the following distinct values: +.TP +.BR LIBCOOPGAMMA_NO " = 0" +Gamma adjustments are not supported. +.TP +.BR LIBCOOPGAMMA_MAYBE " = 1" +Don't know whether gamma adjustments are supported. +.TP +.BR LIBCOOPGAMMA_YES " = 2" +Gamma adjustments are supported. +.P +The +.B +header defines +.I "enum libcoopgamma_depth" +with the alias +.I libcoopgamma_depth_t +and the following distinct values: +.TP +.BR LIBCOOPGAMMA_UINT8 " = 8" +Gamma ramps with +.I uint8_t +as the stop-type are used +.RI ( libcoopgamma_ramps8_t ). +.TP +.BR LIBCOOPGAMMA_UINT16 " = 16" +Gamma ramps with +.I uint16_t +as the stop-type are used +.RI ( libcoopgamma_ramps16_t ). +.TP +.BR LIBCOOPGAMMA_UINT32 " = 32" +Gamma ramps with +.I uint32_t +as the stop-type are used +.RI ( libcoopgamma_ramps32_t ). +.TP +.BR LIBCOOPGAMMA_UINT64 " = 64" +Gamma ramps with +.I uint64_t +as the stop-type are used +.RI ( libcoopgamma_ramps64_t ). +.TP +.BR LIBCOOPGAMMA_FLOAT " < 0" +Gamma ramps with +.I float +as the stop-type are used +.RI ( libcoopgamma_rampsf_t ). +.TP +.BR LIBCOOPGAMMA_DOUBLE " < 0" +Gamma ramps with +.I double +as the stop-type are used +.RI ( libcoopgamma_rampsd_t ). +.P +The +.B +header defines +.I "enum libcoopgamma_lifespan" +with the alias +.I libcoopgamma_lifespan_t +and the following distinct values: +.TP +.BR LIBCOOPGAMMA_REMOVE " = 0" +Remove the filter now. +.TP +.BR LIBCOOPGAMMA_UNTIL_DEATH " > 0" +Remove the filter when disconnecting from the coopgamma +server, or even explicitly removed, whichever comes first. +.TP +.BR LIBCOOPGAMMA_UNTIL_REMOVAL " > 0" +Only remove the filter when it is explicitly requested. +.P +The +.B +header defines +.I "struct libcoopgamma_ramps8" +.RI ( libcoopgamma_ramps8_t ), +.I "struct libcoopgamma_ramps16" +.RI ( libcoopgamma_ramps16_t ), +.I "struct libcoopgamma_ramps32" +.RI ( libcoopgamma_ramps32_t ), +.I "struct libcoopgamma_ramps64" +.RI ( libcoopgamma_ramps64_t ), +.I "struct libcoopgamma_rampsf" +.RI ( libcoopgamma_rampsf_t ), +.I "struct libcoopgamma_rampsd" +.RI ( libcoopgamma_rampsd_t ), +with the following members, +where +.I type +is +.IR uint8_t , +.IR uint16_t , +.IR uint32_t , +.IR uint64_t , +.IR float , +and +.I double +for the respective structures: +.TP +.B "size_t red_size" + The number of stops in the red ramp. +.TP +.B "size_t green_size" +The number of stops in the green ramp. +.TP +.B "size_t blue_size" +The number of stops in the blue ramp. +.TP +.IB type " *red" +The red ramp. +.TP +.IB type " *green" +The green ramp. +.TP +.IB type " *blue" +The blue ramp. +.P +The +.B +header defines +.I "union libcoopgamma_ramps" +with alias +.I libcoopgamma_ramps_t +and the follow members: +.TP +.B "libcoopgamma_ramps8_t u8" +.TP +.B "libcoopgamma_ramps16_t u16" +.TP +.B "libcoopgamma_ramps32_t u32" +.TP +.B "libcoopgamma_ramps64_t u64" +.TP +.B "libcoopgamma_rampsf_t f" +.TP +.B "libcoopgamma_rampsd_t d" +.P +The +.B +header defines +.I "struct libcoopgamma_filter" +with alias +.I libcoopgamma_filter_t +and the follow members: +.TP +.B "int64_t priority" +The priority of the filter, higher priority is applied first. +The gamma correction should have priority 0. +.TP +.B "char *crtc" +The CRTC for which this filter shall be applied. +.TP +.B "char *class" +Identifier for the filter. The syntax must be +\(aq\fI${PACKAGE_NAME}\fP\fB::\fP\fI${COMMAND_NAME}\fP\fB::\fP\fI${RULE}\fP\(aq. +.TP +.B "enum libcoopgamma_lifespan lifespan" +When shall the filter be removed? +If this member's value is +.IR LIBCOOPGAMMA_REMOVE , +only +.I .crtc +and +.I .class +need also be defined. +.TP +.B "enum libcoopgamma_depth depth" +The data type and bit-depth of the ramp stops. +.TP +.B "union libcoopgamma_ramps ramps" +The gamma ramp adjustments of the filter. +.P +The +.B +header defines +.I "struct libcoopgamma_crtc_info" +with alias +.I libcoopgamma_crtc_info_t +and the follow members: +.TP +.B "int cooperative" +Is cooperative gamma server running? +.TP +.B "enum libcoopgamma_depth depth" +The data type and bit-depth of the ramp stops. +.TP +.B "enum libcoopgamma_support supported" +Is gamma adjustments supported on the CRTC? +If not, +.IR .depth , +.IR .red_size , +.IR .green_size , +and +.I .blue_size +are undefined. +.TP +.B "size_t red_size" + The number of stops in the red ramp. +.TP +.B "size_t green_size" +The number of stops in the green ramp. +.TP +.B "size_t blue_size" +The number of stops in the blue ramp. +.P +The +.B +header defines +.I "struct libcoopgamma_filter_query" +with alias +.I libcoopgamma_filter_query_t +and the follow members: +.TP +.B "int64_t high_priority" +Do no return filters with higher priority than this value. +.TP +.B "int64_t low_priority" +Do no return filters with lower priority than this value. +.TP +.B "char *crtc" +The CRTC for which the the current filters shall returned +.TP +.B "int coalesce" +Shall all selected filters be coalesced into one gamma ramp triplet? +.P +The +.B +header defines +.I "struct libcoopgamma_queried_filter" +with alias +.I libcoopgamma_queried_filter_t +and the follow members: +.TP +.B "int64_t priority" +The filter's priority. +.TP +.B "char *class" +The filter's class. +.TP +.B "union libcoopgamma_ramps ramps" +The gamma ramp adjustments of the filter +.P +The +.B +header defines +.I "struct libcoopgamma_filter_table" +with alias +.I libcoopgamma_filter_table_t +and the follow members: +.TP +.B "size_t red_size" +The number of stops in the red ramp. +.TP +.B "size_t green_size" +The number of stops in the green ramp. +.TP +.B "size_t blue_size" +The number of stops in the blue ramp. +.TP +.B "size_t filter_count" +The number of filters. +.TP +.B "struct libcoopgamma_queried_filter_t *filters" +The filters, should be ordered by priority +in descending order (applied first goes first, +applied last goes last), lest there is something +wrong with the coopgamma server. + +If filter coalition was requested, there will +be exactly one filter +.I "(.filter_count == 1)" +and +.I ".filters->class == NULL" +and +.I ".filters->priority" +is undefined. +.TP +.B "enum libcoopgamma_depth depth" +The data type and bit-depth of the ramp stops. +.P +The +.B +header defines +.I "struct libcoopgamma_error" +with alias +.I libcoopgamma_error_t +and the follow members: +.TP +.B "uint64_t number" +Error code. + +If +.I ".custom" +is false, 0 indicates success, +otherwise, 0 indicates that no +error code has been assigned. +.TP +.B "int custom" +Is this a custom error? +.TP +.B "int server_side" +Did the error occur on the server-side? +.TP +.B "char *description" +Error message, can be, and usually is, +.I NULL +if +.I ".custom" +is false. +.P +The +.B +header defines +.I "struct libcoopgamma_context" +with alias +.I libcoopgamma_context_t +and the follow members and a lot +if internal unlisted members: +.TP +.B "struct libcoopgamma_error error" +The error of the last failed function call +to function that documents that this member +will be set on failure. + +This member is undefined after successful +function call. +.TP +.B "int fd" +File descriptor for the socket that connects +the client to the server. +.P +The +.B +header defines +.I "struct libcoopgamma_async_context" +with alias +.I libcoopgamma_async_context_t. +This structure has only internal members. +.SH "SEE ALSO" +.BR libcoopgamma (7) diff --git a/src/libcoopgamma.h b/src/libcoopgamma.h index e4764bd..019bf0f 100644 --- a/src/libcoopgamma.h +++ b/src/libcoopgamma.h @@ -35,6 +35,8 @@ /** * Unmarshal was successful + * + * This value will always be zero */ #define LIBCOOPGAMMA_SUCCESS 0 @@ -42,6 +44,8 @@ * Unmarshal failed: the marshalled data was created * with a older version of libcoopgamma that does not * marshall the data in a compatible way + * + * This value will always be positive */ #define LIBCOOPGAMMA_INCOMPATIBLE_DOWNGRADE 1 @@ -49,11 +53,16 @@ * Unmarshal failed: the marshalled data was created with * a newer version libcoopgamma that does not marshall * the data in a compatible way + * + * This value will always be positive */ #define LIBCOOPGAMMA_INCOMPATIBLE_UPGRADE 2 /** * Unmarshal failed because of an error, `errno` has been set + * + * This value will always be -1 and will be the + * only negative value in this category of constants */ #define LIBCOOPGAMMA_ERRNO_SET -1 @@ -153,17 +162,23 @@ typedef enum libcoopgamma_support { /** * Gamma adjustments are not supported + * + * This value will always be 0 */ LIBCOOPGAMMA_NO = 0, /** * Don't know whether gamma - ' adjustments are supported + * adjustments are supported + * + * This value will always be 1 */ LIBCOOPGAMMA_MAYBE = 1, /** * Gamma adjustments are supported + * + * This value will always be 2 */ LIBCOOPGAMMA_YES = 2 @@ -173,6 +188,10 @@ typedef enum libcoopgamma_support /** * Values used to tell which datatype * is used for the gamma ramp stops + * + * The values will always be the number + * of bits for integral types, and + * negative for floating-point types */ typedef enum libcoopgamma_depth { @@ -217,6 +236,8 @@ typedef enum libcoopgamma_lifespan { /** * Remove the filter now + * + * This value will always be 0 */ LIBCOOPGAMMA_REMOVE = 0, @@ -319,6 +340,44 @@ LIBCOOPGAMMA_RAMPS__(f, float); LIBCOOPGAMMA_RAMPS__(d, double); +/** + * Union with all ramp types. + */ +typedef union libcoopgamma_ramps +{ + /** + * 8-bit version + */ + libcoopgamma_ramps8_t u8; + + /** + * 16-bit version + */ + libcoopgamma_ramps16_t u16; + + /** + * 32-bit version + */ + libcoopgamma_ramps32_t u32; + + /** + * 64-bit version + */ + libcoopgamma_ramps64_t u64; + + /** + * Single precision floating-point version + */ + libcoopgamma_rampsf_t f; + + /** + * Double precision floating-point version + */ + libcoopgamma_rampsd_t d; + +} libcoopgamma_ramps_t; + + /** * Data set to the coopgamma server to apply, * update, or remove a filter. @@ -360,39 +419,7 @@ typedef struct libcoopgamma_filter /** * The gamma ramp adjustments of the filter */ - union - { - /** - * 8-bit version - */ - libcoopgamma_ramps8_t u8; - - /** - * 16-bit version - */ - libcoopgamma_ramps16_t u16; - - /** - * 32-bit version - */ - libcoopgamma_ramps32_t u32; - - /** - * 64-bit version - */ - libcoopgamma_ramps64_t u64; - - /** - * Single precision floating-point version - */ - libcoopgamma_rampsf_t f; - - /** - * Double precision floating-point version - */ - libcoopgamma_rampsd_t d; - - } ramps; + libcoopgamma_ramps_t ramps; } libcoopgamma_filter_t; @@ -403,7 +430,7 @@ typedef struct libcoopgamma_filter typedef struct libcoopgamma_crtc_info { /** - * Cooperative gamma server is running + * Is cooperative gamma server running? */ int cooperative; @@ -499,39 +526,7 @@ typedef struct libcoopgamma_queried_filter /** * The gamma ramp adjustments of the filter */ - union - { - /** - * 8-bit version - */ - libcoopgamma_ramps8_t u8; - - /** - * 16-bit version - */ - libcoopgamma_ramps16_t u16; - - /** - * 32-bit version - */ - libcoopgamma_ramps32_t u32; - - /** - * 64-bit version - */ - libcoopgamma_ramps64_t u64; - - /** - * Single precision floating-point version - */ - libcoopgamma_rampsf_t f; - - /** - * Double precision floating-point version - */ - libcoopgamma_rampsd_t d; - - } ramps; + libcoopgamma_ramps_t ramps; } libcoopgamma_queried_filter_t; @@ -593,11 +588,11 @@ typedef struct libcoopgamma_filter_table typedef struct libcoopgamma_error { /** - * Error code number + * Error code * * If `.custom` is false, 0 indicates * success, otherwise, 0 indicates that - * no error number has been assigned + * no error code has been assigned */ uint64_t number; @@ -641,6 +636,8 @@ typedef struct libcoopgamma_context */ int fd; + /* The members below are internal. */ + /** * Whether `libcoopgamma_synchronise` have * read the empty end-of-headers line @@ -730,6 +727,8 @@ typedef struct libcoopgamma_context */ typedef struct libcoopgamma_async_context { + /* All members are internal. */ + /** * The value of the 'In response to' header * in the waited message -- cgit v1.2.3-70-g09d2