diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/libred.7 | 15 | ||||
| -rw-r--r-- | man/libred.h.0 | 152 | ||||
| -rw-r--r-- | man/libred_check_timetravel.3 | 38 | ||||
| -rw-r--r-- | man/libred_get_colour.3 | 74 | ||||
| -rw-r--r-- | man/libred_init_colour.3 | 41 | ||||
| -rw-r--r-- | man/libred_solar_elevation.3 | 48 | ||||
| -rw-r--r-- | man/libred_term_colour.3 | 33 |
7 files changed, 401 insertions, 0 deletions
diff --git a/man/libred.7 b/man/libred.7 new file mode 100644 index 0000000..a5a6f36 --- /dev/null +++ b/man/libred.7 @@ -0,0 +1,15 @@ +.TH LIBRED 7 LIBRED +.SH NAME +libred \- Solar elevation and blackbody colour calculation +.SH DESCRIPTION +.B libred +is a C library for calculating the Sun's apparent elevation +and colours temperatures. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.BR libred.h (0), +.BR solar-python (7), +.BR redshift (1), +.BR blueshift (1), +.BR libgamma (7) diff --git a/man/libred.h.0 b/man/libred.h.0 new file mode 100644 index 0000000..95a5144 --- /dev/null +++ b/man/libred.h.0 @@ -0,0 +1,152 @@ +.\" -*- 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, otherwise, 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, otherwise, 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, otherwise, 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, otherwise, 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 (7), +.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) diff --git a/man/libred_check_timetravel.3 b/man/libred_check_timetravel.3 new file mode 100644 index 0000000..1d34d39 --- /dev/null +++ b/man/libred_check_timetravel.3 @@ -0,0 +1,38 @@ +.TH LIBRED_CHECK_TIMETRAVEL 3 LIBRED +.SH NAME +libred_check_timetravel \- Exit the process if the clock is too far in the past +.SH SYNOPSIS +.nf +#include <libred.h> + +int \fBlibred_check_timetravel\fP(void); +.fi +.PP +Link with +.IR -lred . +.SH DESCRIPTION +.B libred_check_timetravel +exits the process if +.B libred +is not compiled to support the current time, which is the case +if it was compiled without +.I \-DTIMETRAVELLER +and the clock is before year 2000.5 in the Julian calendar. Before +exiting, the function will print an informative error message to +standard error. +.SH "RETURN VALUE" +Upon successful completion, without time incompatibility, the function +returns 0. Upon failure, that is, it is unable to read the clock, the +function returns -1. +.SH ERRORS +The function may fail for any reason specified for +.BR clock_gettime (3), +and set the value of +.B errno +to the same values. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.BR libred.h (0), +.BR libred (7), +.BR libred_solar_elevation (3) diff --git a/man/libred_get_colour.3 b/man/libred_get_colour.3 new file mode 100644 index 0000000..fd32eb3 --- /dev/null +++ b/man/libred_get_colour.3 @@ -0,0 +1,74 @@ +.TH LIBRED_GET_COLOUR 3 LIBRED +.SH NAME +libred_get_colour \- Calculate a colour temperature +.SH SYNOPSIS +.nf +#include <libred.h> + +int \fBlibred_get_colour\fP(long int \fItemp\fP, double* \fIr\fP, double* \fIg\fP, double* \fIb\fP); +.fi +.PP +Link with +.IR -lred . +.SH DESCRIPTION +.B libred_get_colour +gets or interpolates the colour temperature for +.I temp +kelvins, and returns the colour temperature in sRGB. The values, +between 0.0 and 1.0, for the "red", green, and blue channels +are stored in +.IR *r , +.IR *g , +and +.IR *b , +respectively. +.PP +At least one of the values will be 1.0, none will be greater than +1.0, and none will be less than 0.0. It is guaranteed (unless the +resources file has been modified) that +.IR *r , +.IR *g , +and +.I *b +all will be 1.0 if +.I temp +is 6500. +.PP +You must call +.BR libred_init_colour (3) +before the first use of this function, +and you should call +.BR libred_term_colour (3) +after the last use of this function. +.SH "RETURN VALUE" +Upon successful completion, the function returns 0. On failure, +the function returns -1 and sets +.B errno +appropriately. +.SH ERRORS +The function may fail if: +.TP +.B EOVERFLOW +The colour temperature lookup table is smaller than it should be. +.TP +.B EDOM +If +.I temp +is less than +.B LIBRED_LOWEST_TEMPERATURE +(which is 1000.) +.PP +The function may also fail for any reason specified for +.BR pread (3), +and set the value of +.B errno +to the same values. +.SH "FUTURE DIRECTIONS" +It is possible that the behaviour is changed to loading the +colour temperature lookup table rather than just open a +file descriptor to it. +.SH "SEE ALSO" +.BR libred.h (0), +.BR libred (7), +.BR libred_init_colour (3), +.BR libred_term_colour (3) diff --git a/man/libred_init_colour.3 b/man/libred_init_colour.3 new file mode 100644 index 0000000..9463245 --- /dev/null +++ b/man/libred_init_colour.3 @@ -0,0 +1,41 @@ +.TH LIBRED_INIT_COLOUR 3 LIBRED +.SH NAME +libred_init_colour \- Prepare for use of libred_get_colour(3) +.SH SYNOPSIS +.nf +#include <libred.h> + +int \fBlibred_init_colour\fP(void); +.fi +.PP +Link with +.IR -lred . +.SH DESCRIPTION +.B libred_init_colour +open a file descriptor, without returning it, to the colour +temperature lookup table, and stores the file descriptor to +.BR libred_fd . +It is necessary to call this function before the first call to +.BR libred_get_colour (3). +.SH "RETURN VALUE" +Upon successful completion, the function returns 0. On failure, +the function returns -1 and sets +.B errno +appropriately. +.SH ERRORS +The function may fail for any reason specified for +.BR open (3), +and set the value of +.B errno +to the same values. +.B errno +is always set to 0 on success. +.SH "FUTURE DIRECTIONS" +It is possible that the behaviour is changed to loading the +colour temperature lookup table rather than just open a +file descriptor to it. +.SH "SEE ALSO" +.BR libred.h (0), +.BR libred (7), +.BR libred_get_colour (3), +.BR libred_term_colour (3) diff --git a/man/libred_solar_elevation.3 b/man/libred_solar_elevation.3 new file mode 100644 index 0000000..7fd499f --- /dev/null +++ b/man/libred_solar_elevation.3 @@ -0,0 +1,48 @@ +.TH LIBRED_SOLAR_ELEVATION 3 LIBRED +.SH NAME +libred_solar_elevation \- Calculate the Sun's apparent elevation +.SH SYNOPSIS +.nf +#include <libred.h> + +double \fBlibred_solar_elevation\fP(double \fIlatitude\fP, double \fIlongitude\fP); +.fi +.PP +Link with +.IR -lred . +.SH DESCRIPTION +.B libred_solar_elevation +calculates the Sun's elevation as apparent from a select geographical position. +Namely from +.I latitude +degrees north of GPS's equator and +.I longitude +degrees east of GPS's prime meridian. The function is only explicitly defined for +values between -90 and +90 for +.I latitude +and values between -180 and +180 for and +.IR longitude . +Other values may or may not work, no error is thrown if used. +.SH "RETURN VALUE" +Upon successful completion, the function sets +.B errno +to 0 and returns the Sun's current apparent elevation, measured in +degrees above the horizon. On failure, the function returns an +arbitrary value (happens to always be 0.0) and sets +.B errno +an a non-zero value. +.SH ERRORS +The function may fail for any reason specified for +.BR clock_gettime (3), +and set the value of +.B errno +to the same values. +.B errno +is always set to 0 on success. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.BR libred.h (0), +.BR libred (7), +.BR libred_check_timetravel (3), +.BR libred_init_colour (3) diff --git a/man/libred_term_colour.3 b/man/libred_term_colour.3 new file mode 100644 index 0000000..6d327c2 --- /dev/null +++ b/man/libred_term_colour.3 @@ -0,0 +1,33 @@ +.TH LIBRED_TERM_COLOUR 3 LIBRED +.SH NAME +libred_term_colour \- Deallocate resources required by libred_get_colour(3) +.SH SYNOPSIS +.nf +#include <libred.h> + +void \fBlibred_term_colour\fP(void); +.fi +.PP +Link with +.IR -lred . +.SH DESCRIPTION +.B libred_term_colour +deallocates all resources acquired by +.BR libred_init_colour (3). +It is highly recommended to call this function before calling an +.BR exec (3)-function. +If you want to use +.BR libred_get_colour (3) +again after a call to this function has been made, you must first call +.BR libred_init_colour (3). +.SH "RETURN VALUE" +None. +.SH ERRORS +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.BR libred.h (0), +.BR libred (7), +.BR libred_get_colour (3), +.BR libred_init_colour (3) |