Document macros, enums, structs, and unions in libcoopgamma.h.0

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

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