1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
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)
|
