diff options
Diffstat (limited to 'src/common.h')
| -rw-r--r-- | src/common.h | 384 |
1 files changed, 339 insertions, 45 deletions
diff --git a/src/common.h b/src/common.h index 704e64a..e3cc37b 100644 --- a/src/common.h +++ b/src/common.h @@ -282,19 +282,56 @@ typedef struct gamma_state GAMMA_STATE; typedef struct location_state LOCATION_STATE; +/** + * The time of the day: day, night, or twilight + */ enum period { - PERIOD_NONE = 0, + /** + * None applied + */ + PERIOD_NONE, + + /** + * Full daytime + */ PERIOD_DAYTIME, + + /** + * Full nighttime + */ PERIOD_NIGHT, + + /** + * Transitioning between day and night + * (either direction) (twilight) + */ PERIOD_TRANSITION }; + +/** + * The mode the program is running in + */ enum program_mode { + /** + * Run in foreground continually update temperature + */ PROGRAM_MODE_CONTINUAL, + + /** + * Update temperature once then exit + */ PROGRAM_MODE_ONE_SHOT, + + /** + * Print setting and exit + */ PROGRAM_MODE_PRINT, - PROGRAM_MODE_RESET, - PROGRAM_MODE_MANUAL + + /** + * Remove effects and exit + */ + PROGRAM_MODE_RESET }; @@ -413,35 +450,94 @@ struct colour_setting { }; -/* Time range. - Fields are offsets from midnight in seconds. */ -struct time_range { - time_t start; - time_t end; -}; - - +/** + * Linked list of time periods for `CLOCK_SCHEME` + */ struct time_period { + /** + * The number of seconds after midnight the period starts + */ time_t start; + + /** + * 1 if at daytime at the the time `.start`, + * 0 if at nighttime at the the time `.start` + */ double day_level; + + /** + * `.next->day_level - .day_level` dividied by + * the duration of the period, in seconds + * + * `.day_level` is added to the number of seconds + * elapsed since `.start` multiplied by this number + * to get the dayness level at that time + */ double diff_over_duration; + + /** + * The following time period + */ const struct time_period *next; }; -/* Transition scheme. - The solar elevations at which the transition begins/ends */ +/** + * Dayness level scheme + */ union scheme { + /** + * The scheme type + * + * If `STATIC_SCHEME`, the union contains no scheme data + */ enum scheme_type type; - struct { + + /** + * Used if `.type == SOLAR_SCHEME` + */ + struct solar_scheme { + /** + * `SOLAR_SCHEME` + */ enum scheme_type type; + + /** + * The lowest solar elevation of daytime + */ double high; + + /** + * The highest solar elevation of nighttime + */ double low; + + /** + * `.high - .low` + */ double range; } elevation; - struct { + + /** + * Used if `.type == CLOCK_SCHEME` + */ + struct clock_scheme { + /** + * `CLOCK_SCHEME` + */ enum scheme_type type; + + /** + * Circularly linked list of time periods + * + * The application will update this to always + * point to the current time period + */ const struct time_period *periods; + + /** + * The memory allocation for the nodes in `.periods` + */ struct time_period periods_array[4]; } time; }; @@ -521,10 +617,6 @@ struct settings { const struct location_provider *provider; /* Arguments for location provider. */ char *provider_args; - - enum program_mode mode; - int verbose; - enum scheme_type scheme_type; }; @@ -532,53 +624,202 @@ struct settings { * Adjustment method information and interface */ struct gamma_method { + /** + * The name of the adjustment method + */ const char *name; - /* If true, this method will be tried if none is explicitly chosen. */ + /** + * 1 if the method should be tried if none is explicitly chosen, + * 0 otherwise + */ int autostart; - /* Initialize state. Options can be set between init and start. */ - int (*init)(GAMMA_STATE **state); - /* Allocate storage and make connections that depend on options. */ - int (*start)(GAMMA_STATE *state, enum program_mode mode); - /* Free all allocated storage and close connections. */ - void (*free)(GAMMA_STATE *state); + /** + * Create an initialised state object + * + * @param state_out Output parameter for the state object + * @return 0 on success, -1 on failure + * + * `*state_out` is set (potentially to `NULL`) on failure + */ + int (*create)(GAMMA_STATE **state_out); - /* Print help on options for this adjustment method. */ - void (*print_help)(FILE *f); - /* Set an option key, value-pair */ + /** + * Configure the adjustment method + * + * @param state State object for the adjustment method + * @param key Option to configure + * @param value Option value to set + * @return 0 on success, -1 on failure + */ int (*set_option)(GAMMA_STATE *state, const char *key, const char *value); - /* Restore the adjustment to the state before start was called. */ + /** + * Print help on options for the adjustment method + * + * @param f Output sink + */ + void (*print_help)(FILE *f); + + /** + * Finalise option-dependent initialisation and connections + * + * @param state State object for the adjustment method + * @return 0 on success, -1 on failure + */ + int (*start)(GAMMA_STATE *state); + + /** + * Apply colour settings + * + * @param state State object for the adjustment method + * @param settings The colour settings to apply + * @param preserve Whether currently applied adjustments (assumed + * to be colour calibration) shall remain applied + * @return 0 on success, -1 on failure + */ + int (*apply)(GAMMA_STATE *state, const struct colour_setting *setting, int preserve); + + /** + * Restore the adjustments to the `.state` before start was called + * + * @param state State object for the adjustment method + */ void (*restore)(GAMMA_STATE *state); - /* Set a specific colour temperature. */ - int (*set_temperature)(GAMMA_STATE *state, const struct colour_setting *setting, int preserve); + + /** + * Close connections and deallocate all state resources + * + * @param state The state to terminate + * + * The pointer `state` will become invalid + */ + void (*free)(GAMMA_STATE *state); }; +/** + * Initialiser for `struct gamma_method` + * + * @param NAME:const char * Value for `.name` + * @param AUTOSTART:int Value for `.autostart` + * @param PREFIX:identifier The text, sans terminal underscore (_), prefixed to the + * names of each function implementing the adjustment method + */ +#define GAMMA_METHOD_INIT(NAME, AUTOSTART, PREFIX)\ + {\ + .name = (NAME),\ + .autostart = (AUTOSTART),\ + .create = &PREFIX##_create,\ + .set_option = &PREFIX##_set_option,\ + .print_help = &PREFIX##_print_help,\ + .start = &PREFIX##_start,\ + .free = &PREFIX##_free,\ + .restore = &PREFIX##_restore,\ + .apply = &PREFIX##_apply\ + } + /** * Location provider information and interface */ struct location_provider { + /** + * The name of the location provider + */ const char *name; - /* Initialize state. Options can be set between init and start. */ - int (*init)(LOCATION_STATE **state); - /* Allocate storage and make connections that depend on options. */ - int (*start)(LOCATION_STATE *state); - /* Free all allocated storage and close connections. */ - void (*free)(LOCATION_STATE *state); + /** + * Create an initialised state object + * + * @param state_out Output parameter for the state object + * @return 0 on success, -1 on failure + * + * `*state_out` is set (potentially to `NULL`) on failure + */ + int (*create)(LOCATION_STATE **state_out); - /* Print help on options for this location provider. */ - void (*print_help)(FILE *f); - /* Set an option key, value-pair. */ + /** + * Configure the location provider + * + * @param state State object for the location provider + * @param key Option to configure + * @param value Option value to set + * @return 0 on success, -1 on failure + */ int (*set_option)(LOCATION_STATE *state, const char *key, const char *value); - /* Listen and handle location updates. */ + /** + * Print help on options for the location provider + * + * @param f Output sink + */ + void (*print_help)(FILE *f); + + /** + * Finalise option-dependent initialisation and connections + * + * @param state State object for the location provider + * @return 0 on success, -1 on failure + */ + int (*start)(LOCATION_STATE *state); + + /** + * Get the file descriptor used by the location provider + * + * The application may use it for detecting when there + * is data available for `.handle` to act upon + * + * @param state State object for the location provider + * @return The file descriptor used by location provider, -1 if none + */ int (*get_fd)(LOCATION_STATE *state); - int (*handle)(LOCATION_STATE *state, struct location *location, int *available); + + /** + * Get the current location + * + * This function shall only be caused if `.get_fd` returns -1 + * or the file descriptor it returns has data available on it + * as indicated by input polling, otherwise `*location` and + * `*available` will not be set + * + * @param state State object for the location provider + * @param location_out Output parameter for the current location + * @param available_out Output parameter for whether the location provider + * is currently available + * @return 0 on success, -1 on unrecoverable failure + */ + int (*fetch)(LOCATION_STATE *state, struct location *location, int *available); + + /** + * Close connections and deallocate all state resources + * + * @param state The state to terminate + * + * The pointer `state` will become invalid + */ + void (*free)(LOCATION_STATE *state); }; +/** + * Initialiser for `struct location_provider` + * + * @param NAME:const char * Value for `.name` + * @param PREFIX:identifier The text, sans terminal underscore (_), prefixed to the + * names of each function implementing the location provider + */ +#define LOCATION_PROVIDER_INIT(NAME, PREFIX)\ + {\ + .name = (NAME),\ + .create = &PREFIX##_create,\ + .set_option = &PREFIX##_set_option,\ + .print_help = &PREFIX##_print_help,\ + .start = &PREFIX##_start,\ + .get_fd = &PREFIX##_get_fd,\ + .fetch = &PREFIX##_fetch,\ + .free = &PREFIX##_free\ + } + /** * `NULL` terminated list of adjustment methods @@ -615,9 +856,41 @@ extern struct colour_setting night_settings; */ extern union scheme scheme; +/** + * Whether the application is in verbose mode + */ +extern int verbose; + +/** + * The mode the application is running in + */ +extern enum program_mode mode; + /* colour.c */ +/** + * Interpolate between two colour settings + * + * @param a The first colour setting, used wholly when `t` is 0 + * @param b The second colour setting, used wholly when `t` is 1 + * @param t The degree to which `second` second be applied + * @param result Output parameter for `(1 - t) * a + t * b` + */ +void interpolate_colour_settings(const struct colour_setting *a, const struct colour_setting *b, + double t, struct colour_setting *result); + +/** + * Check whether the differences between two colours settings + * are large enough to warrant fading between the two + * + * @param a The first colour setting + * @param b The second colour setting + * @return 1 if the difference between `a` and `b` is large, 0 otherwise + */ +GCC_ONLY(__attribute__((__pure__))) +int colour_setting_diff_is_major(const struct colour_setting *a, const struct colour_setting *b); + #define LIST_RAMPS_STOP_VALUE_TYPES(X, D)\ X(u8, uint8_t, UINT8_MAX, 8) D\ X(u16, uint16_t, UINT16_MAX, 16) D\ @@ -699,6 +972,23 @@ int get_location(const struct location_provider *provider, LOCATION_STATE *state void acquire_location_provider(struct settings *settings, LOCATION_STATE **location_state_out); +/** + * Check whether location is valid + * + * If the message is invalid, and error message is printed + * + * @param location The location to check + * @return 1 if the location is valid, 0 otherwise + */ +int location_is_valid(const struct location *location); + +/** + * Print the current location to standard output + * + * @param location The current location + */ +void print_location(const struct location *location); + /* hooks.c */ @@ -772,15 +1062,19 @@ FILE *try_path_fopen(const struct env_path *path_spec, const char **path_out, ch */ DIR *try_path_opendir(const struct env_path *path_spec, const char **path_out, char **pathbuf_out); +#ifndef WINDOWS /** - * Create a pipe(7) where both ends have `O_NONBLOCK` applied + * Create a pipe(7) where both ends have `O_CLOEXEC` and, + * if available for pipes, `O_DIRECT`, applied, the read-end + * will also have `O_NONBLOCK` applied * * @param pipefds Output parameter for the pipe's file descriptors: * 0) reading file descriptor, and * 1) writing file descriptor * @return 0 on success, -1 on failure */ -int pipe_nonblock(int pipefds[2]); +int pipe_rdnonblock(int pipefds[2]); +#endif extern const struct gamma_method dummy_gamma_method; |