aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--README3
-rw-r--r--doc/man/libcoopgamma.74
-rw-r--r--doc/man/libcoopgamma.h.0388
-rw-r--r--src/libcoopgamma.h139
4 files changed, 462 insertions, 72 deletions
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 <libcoopgamma.h>
+.fi
+.SH "DESCRIPTION"
+The
+.B <libcoopgamma.h>
+header includes the
+.BR <limits.h> ,
+.BR <stddef.h> ,
+and
+.BR <stdint.h>
+headers.
+.P
+The
+.B <libcoopgamma.h>
+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 <libcoopgamma.h>
+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 <libcoopgamma.h>
+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 <libcoopgamma.h>
+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 <libcoopgamma.h>
+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 <libcoopgamma.h>
+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 <libcoopgamma.h>
+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 <libcoopgamma.h>
+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 <libcoopgamma.h>
+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 <libcoopgamma.h>
+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 <libcoopgamma.h>
+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 <libcoopgamma.h>
+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 <libcoopgamma.h>
+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 <libcoopgamma.h>
+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,
@@ -320,6 +341,44 @@ 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