diff options
| -rw-r--r-- | doc/man/libred.h.0 | 168 | ||||
| -rw-r--r-- | src/libred.h | 6 |
2 files changed, 174 insertions, 0 deletions
diff --git a/doc/man/libred.h.0 b/doc/man/libred.h.0 new file mode 100644 index 0000000..310b794 --- /dev/null +++ b/doc/man/libred.h.0 @@ -0,0 +1,168 @@ +.\" -*- nroff -*- +.TH LIBRED.H 0 LIBRED "" "Library Headers" +.SH NAME +libred.h \- Solar elevation and blackbody colour calculation +.SH SYNOPSIS +.nf +#include <libred.h> +.fi +.PP +Link with +.IR -lred . +.SH DESCRIPTION +The +.I <libred.h> +header defines macros, symbolic constants, and functions for +calculating solar elevations and blackbody colours. All macros +and symbolic constants in this header are suitable for use in +.B #if +preprocessing directives. +.PP +This header defines the follow symbolic constants: +.TP +.B LIBRED_SOLAR_APPARENT_RADIUS +The approximate apparent size of the Sun in degrees. This +value should be about 0.5(3). +.TP +.B LIBRED_SOLAR_ELEVATION_SUNSET_SUNRISE +The Sun's elevation at sunset and sunrise, measured in degrees. +This value will always be 0.0. +.TP +.B LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN +The Sun's elevation at civil dusk and civil dawn, measured in +degrees. This value will always be -6.0. +.TP +.B LIBRED_SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN +The Sun's elevation at nautical dusk and nautical dawn, measured +in degrees. This value will always be -12.0. +.TP +.B LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN +The Sun's elevation at astronomical dusk and astronomical dawn, +measured in degrees. This value will always be -18.0. +.TP +.B LIBRED_HIGHEST_TEMPERATURE +The highest temperature, in kelvins, for which there is a colour +temperature in the table of colour temperature. Any temperature +above this is automatically truncated by +.BR libred_get_colour (3), +as higher values shall be unnoticeable. Currently, this value +is 40\ 000. +.TP +.B LIBRED_LOWEST_TEMPERATURE +The lowest temperature, in kelvins, for which there is a colour +temperature in the table of colour temperature. Any temperature +below this results in +.BR libred_get_colour (3) +failing and setting +.B errno +to +.BR EDOM . +Currently this value 1000, hypothetical changes will be very small. +.TP +.B LIBRED_DELTA_TEMPERATURE +The temperatures differences between sequential colour temperatures +in the colour temperatures look up table. Currently this value is 100. +.PP +This header defines the follow macros: +.TP +.BR LIBRED_IS_TWILIGHT "(const double)" +Evaluates to 1 if the given expression is between -18.0 and 0.0 (this is, +between +.B LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN +and +.BR LIBRED_SOLAR_ELEVATION_SUNSET_SUNRISE ), +inclusively, other wise, this macro evaluates to 0. The input should be the +Sun's apparent elevation, and the macro evaluates to 1 if it is currently +twilight. The given expression is evaluted either once or twice, therefore, +it must not have side-effects. +.TP +.BR LIBRED_IS_CIVIL_TWILIGHT "(const double)" +Evaluates to 1 if the given expression is between -6.0 and 0.0 (this is, +between +.B LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN +and +.BR LIBRED_SOLAR_ELEVATION_SUNSET_SUNRISE ), +inclusively, other wise, this macro evaluates to 0. The input should be the +Sun's apparent elevation, and the macro evaluates to 1 if it is currently +civil twilight. The given expression is evaluted either once or twice, +therefore, it must not have side-effects. +.TP +.BR LIBRED_IS_NAUTICAL_TWILIGHT "(const double)" +Evaluates to 1 if the given expression is between -12.0 and -6.0 (this is, +between +.B LIBRED_SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN +and +.BR LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN ), +inclusively, other wise, this macro evaluates to 0. The input should be the +Sun's apparent elevation, and the macro evaluates to 1 if it is currently +nautical twilight. The given expression is evaluted either once or twice, +therefore, it must not have side-effects. +.TP +.BR LIBRED_IS_ASTRONOMICAL_TWILIGHT "(const double)" +Evaluates to 1 if the given expression is between -18.0 and -12.0 (this is, +between +.B LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN +and +.BR LIBRED_SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN ), +inclusively, other wise, this macro evaluates to 0. The input should be the +Sun's apparent elevation, and the macro evaluates to 1 if it is currently +astronomical twilight. The given expression is evaluted either once or twice, +therefore, it must not have side-effects. +.PP +Note that the intervals are closed, and hence their boundaries overlap. +This is intentional. If it is not twilight it is either daytime or night. +It is night only if the Sun's apparent elevation is negative. +.PP +This header defines the following functions: +.TP +* +.BR libred_solar_elevation (3) +.TP +* +.BR libred_check_timetravel (3) +.TP +* +.BR libred_init_colour (3) +.TP +* +.BR libred_term_colour (3) +.TP +* +.BR libred_get_colour (3) +.PP +This header may define +.B extern int libred_fd +iff it does it also defines the macro +.BR LIBRED_HAVE_FD . +If it does, you want to keep this file descriptor open when you daemonise +your process. It is set by +.BR libred_init_colour (3) +and unset by +.BR libred_term_colour (3). +It value is negative (more precisely it is -1) if no file descriptor has +been opened. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.BR libred_solar_elevation (3), +.BR libred_check_timetravel (3), +.BR libred_init_colour (3), +.BR libred_term_colour (3), +.BR libred_get_colour (3) +.SH LICENSE +Copyright \(co 2016 Mattias Andrée +.br +License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>. +.br +This is free software: you are free to change and redistribute it. +.br +There is NO WARRANTY, to the extent permitted by law. +.PP +Copying and distribution of this manual, with or without modification, +are permitted in any medium without royalty provided the copyright +notice and this notice are preserved. This file is offered as-is, +without any warranty. +.SH BUGS +Please report bugs to <https://github.com/maandree/libred/issues> +or to <maandree@member.fsf.org>. + diff --git a/src/libred.h b/src/libred.h index 9a2f7ba..5258de7 100644 --- a/src/libred.h +++ b/src/libred.h @@ -125,9 +125,15 @@ int libred_check_timetravel(void); /** * The file descriptor to the colour lookup table. + * -1 if none is open. */ extern int libred_fd; +/** + * Iff this macro is define `libred_fd` is available. + */ +#define LIBRED_HAVE_FD 1 + /** * This function must be called, once, |