diff options
| -rw-r--r-- | Makefile.in | 5 | ||||
| -rw-r--r-- | doc/info/chap/constants.texinfo | 47 | ||||
| -rw-r--r-- | doc/info/chap/functions.texinfo | 155 | ||||
| -rw-r--r-- | doc/info/chap/macros.texinfo | 49 | ||||
| -rw-r--r-- | doc/info/chap/overview.texinfo | 6 | ||||
| -rw-r--r-- | doc/info/chap/variables.texinfo | 15 | ||||
| -rw-r--r-- | doc/info/content.texinfo | 8 | ||||
| -rw-r--r-- | doc/man/libred.h.0 | 8 | ||||
| -rw-r--r-- | doc/man/libred_get_colour.3 | 2 | ||||
| -rw-r--r-- | doc/man/libred_solar_elevation.3 | 2 |
10 files changed, 288 insertions, 9 deletions
diff --git a/Makefile.in b/Makefile.in index b34fcf6..00b0881 100644 --- a/Makefile.in +++ b/Makefile.in @@ -60,7 +60,8 @@ _TEXINFO_DIRLEVELS = 2 _INFOPARTS = 0 _HAVE_TEXINFO_MANUAL = yes _HTML_FILES = Free-Software-Needs-Free-Documentation.html GNU-Free-Documentation-License.html \ - GNU-General-Public-License.html index.html Overview.html + GNU-General-Public-License.html index.html Overview.html Functions.html \ + Constants.html Macros.html Variables.html # Used by mk/man.mk _MAN_PAGE_SECTIONS = 0 3 7 @@ -76,7 +77,7 @@ _COPYING = COPYING ___EVERYTHING_INFO = autohaltd titlepage-data content hardcopy-copying \ appx/fdl appx/free-software-needs-free-documentation appx/gpl \ reusable/macros reusable/paper reusable/titlepage \ - chap/overview + chap/overview chap/variables chap/macros chap/functions chap/constants _EVERYTHING = $(__EVERYTHING_ALL_COMMON) DEPENDENCIES INSTALL NEWS \ $(foreach F,$(___EVERYTHING_INFO),doc/info/$(F).texinfo) \ src/10deg src/blackbody.c src/libred.h src/macros.h \ diff --git a/doc/info/chap/constants.texinfo b/doc/info/chap/constants.texinfo new file mode 100644 index 0000000..e5e09ac --- /dev/null +++ b/doc/info/chap/constants.texinfo @@ -0,0 +1,47 @@ +@node Constants +@chapter Constants + +@file{<libred.h>} defines a number of symbolic constants +suitable for using a @code{#if} preprocessing directives. + +@table @code +@item LIBRED_SOLAR_APPARENT_RADIUS +The approximate apparent size of the Sun in degrees. +This value should be about 0.5(3). + +@item LIBRED_SOLAR_ELEVATION_SUNSET_SUNRISE +The Sun's elevation at sunset and sunrise, measured in +degrees. This value will always be 0.0. + +@item LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN +The Sun's elevation at civil dusk and civil dawn, measured +in degrees. This value will always be @math{-6.0}. + +@item LIBRED_SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN +The Sun's elevation at nautical dusk and nautical dawn, +measured in degrees. This value will always be @math{-12.0}. + +@item LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN +The Sun's elevation at astronomical dusk and astronomical +dawn, measured in degrees. This value will always be @math{-18.0}. + +@item 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 +@code{libred_get_colour}, as higher values shall be +unnoticeable. Currently, this value is 40@tie{}000. + +@item 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 @code{libred_get_colour} +failing and setting @code{errno} to @code{EDOM}. Currently +this value 1000, hypothetical changes will be very small. + +@item LIBRED_DELTA_TEMPERATURE +The temperatures differences between sequential colour +temperatures in the colour temperatures look up table. +Currently this value is 100. +@end table + diff --git a/doc/info/chap/functions.texinfo b/doc/info/chap/functions.texinfo new file mode 100644 index 0000000..d3236ec --- /dev/null +++ b/doc/info/chap/functions.texinfo @@ -0,0 +1,155 @@ +@node Functions +@chapter Functions + +@file{<libred.h>} defines a small number of functions. +@example +int libred_check_timetravel(void); +double libred_solar_elevation(double latitude, double longitude); +int libred_init_colour(void); +void libred_term_colour(void); +int libred_get_colour(long int temp, double* r, double* g, double* b); +@end example + +@code{libred_check_timetravel} exits the process if @command{libred} +is not compiled to support the current time, which is the case if it +was compiled without @option{-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. Upon successful +completion, without time incompatibility, the function returns 0. +Upon failure, that is,it is unable to read the clock, the function +returns @math{-1}. The function may fail for any reason specified for +@code{clock_gettime}, and set the value of errno to the same values. +It is recommended to call this function at the beginning of the program. + +@example +#include <libred.h> +#include <stdio.h> +int main() +@{ + if (libred_check_timetravel()) + return perror(""), 1; + + /* @xrm{}Use @xtt{}libred_solar_elevation@xrm{} to your heart's contempt.@xtt{} */ + + return 0; +@} +@end example + +@code{libred_solar_elevation} calculates the Sun's elevation as apparent +from a select geographical position. Namely from latitude degrees north +of GPS's equator and longitude degrees east of GPS's prime meridian. +The function is only explicitly defined for values between @math{-90} and +@math{+90} for latitude and values between @math{-180} and @math{+180} for +and longitude. Other values may or may not work, no error is thrown if used. +Upon successful completion, the function sets 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 @code{errno} an a non-zero value. The function may fail for +any reason specified for @code{clock_gettime}, and set the value of +@code{errno} to the same values. @code{errno} is always set to 0 on success. + +@example +#include <libred.h> +#include <stdio.h> +#include <stdlib.h> +int main(int argc, char* argv[]) +@{ + double elevation, latitude, longitude; + + if (libred_check_timetravel()) + return perror(""), 1; + + if (argc < 3) return 2; + latitude = atof(argv[1]); + longitude = atof(argv[2]); + + elevation = libred_solar_elevation(latitude, longitude); + return errno || printf("Elevation: %lf\n", elevation) < 0; +@} +@end example + +@code{libred_init_colour} open a file descriptor, without returning it, +to the colour temperature lookup table, and stores the file descriptor to +@code{libred_fd}. It is necessary to call this function before the first +call to @code{libred_get_colour}. Upon successful completion, the +function returns 0. On failure, the function returns @math{-1} and sets +@code{errno} appropriately. The function may fail for any reason specified +for @code{open}, and set the value of @code{errno} to the same values. +@code{errno} is always set to 0 on success. It is possible that the +behaviour is changed to loading the colour temperature lookup table rather +than just open a file descriptor to it. + +@code{libred_term_colour} deallocates all resources acquired by +@code{libred_init_colour}. It is highly recommended to call this function +before calling an @code{exec}-function. If you want to use +@code{libred_get_colour} again after a call to this function has been +made, you must first call @code{libred_init_colour}. + +@example +#include <libred.h> +#include <stdio.h> +int main(int argc, char* argv[]) +@{ + if (libred_init_colour()) + return perror(""), 1; + + /* @xrm{}Use @xtt{}libred_get_colour@xrm{} to your heart's contempt.@xtt{} */ + + libred_term_colour(); + return 0; +@} +@end example + +@code{libred_get_colour} gets or interpolates the colour temperature for +@code{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 @code{*r}, @code{*g}, and @code{*b}, respectively. +Upon successful completion, the function returns 0. On failure, the +function returns @math{-1} and sets @code{errno} appropriately. +The function may fail if: +@table @code +@item EOVERFLOW +The colour temperature lookup table is smaller than it should be. +@item EDOM +If @code{temp} is less than @code{LIBRED_LOWEST_TEMPERATURE} (which is 1000.) +@end table +@noindent +The function may also fail for any reason specified for @code{pread}, and +set the value of @code{errno} to the same values. + +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 @code{*r}, @code{*g}, and @code{*b} all +will be 1.0 if @code{temp} is 6500. + +You must call @code{libred_init_colour} before the first use of +@code{libred_get_colour}, and you should call @code{libred_term_colour} +after the last use of @code{libred_get_colour}. + +@example +#include <libred.h> +#include <stdio.h> +#include <stdlib.h> +int main(int argc, char* argv[]) +@{ + long int temp; + double r, g, b; + + if (argc < 2) return 2; + temp = atol(argv[1]); + + if (libred_init_colour()) + return perror(""), 1; + + if (libred_get_colour(temp, &r, &g, &b)); + return perror(""), libred_term_colour(), 1; + + libred_term_colour(); + + return printf("Red: %lf\n" + "Green: %lf\n" + "Blue: %lf\n", + r, g, b) < 0; +@} +@end example + diff --git a/doc/info/chap/macros.texinfo b/doc/info/chap/macros.texinfo new file mode 100644 index 0000000..2d4a947 --- /dev/null +++ b/doc/info/chap/macros.texinfo @@ -0,0 +1,49 @@ +@node Macros +@chapter Macros + +@file{<libred.h>} defines a small set of macros +suitable for using a @code{#if} preprocessing directives. + +@table @code +@item LIBRED_IS_TWILIGHT(const double) +Evaluates to 1 if the given expression is between @math{-18.0} +and 0.0 (this is, between +@code{LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN} and +@code{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. + +@item LIBRED_IS_CIVIL_TWILIGHT(const double) +Evaluates to 1 if the given expression is between @math{-6.0} +and 0.0 (this is, between +@code{LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN} and +@code{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. + +@item LIBRED_IS_NAUTICAL_TWILIGHT(const double) +Evaluates to 1 if the given expression is between @math{-12.0} +and @math{-6.0} (this is, between +@code{LIBRED_SOLAR_ELEVATION_NAUTICAL_DUSK_DAWN} and +@code{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. + +@item LIBRED_IS_ASTRONOMICAL_TWILIGHT(const double) +Evaluates to 1 if the given expression is between @math{-18.0} +and @math{-12.0} (this is, between +@code{LIBRED_SOLAR_ELEVATION_ASTRONOMICAL_DUSK_DAWN} and +@code{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. +@end table + diff --git a/doc/info/chap/overview.texinfo b/doc/info/chap/overview.texinfo index 3571e63..34f0f71 100644 --- a/doc/info/chap/overview.texinfo +++ b/doc/info/chap/overview.texinfo @@ -5,3 +5,9 @@ the Sun's apparent elevation, and colour temperatures, the colour of blackbodies. +To use @command{libred}, include the header file +@file{<libred.h>}, and link with @option{-lred}. The +@command{libred} package includes a @command{librarian} +file and a @command{pkgconfig} file, both named +@command{libred}. + diff --git a/doc/info/chap/variables.texinfo b/doc/info/chap/variables.texinfo new file mode 100644 index 0000000..aa44f19 --- /dev/null +++ b/doc/info/chap/variables.texinfo @@ -0,0 +1,15 @@ +@node Variables +@chapter Variables + +@file{<libred.h>} defines the variable +@example +extern int libred_fd +@end example +@indent +which is either @code{-1} or the file descriptor the +library uses to access the colour temperature lookup +table. The header also defines @code{LIBRED_HAVE_FD}. +It is possible that @code{libred_fd} is removed in a +future version. If it is, @code{LIBRED_HAVE_FD} will +be removed too. + diff --git a/doc/info/content.texinfo b/doc/info/content.texinfo index 8ff128d..25719b2 100644 --- a/doc/info/content.texinfo +++ b/doc/info/content.texinfo @@ -9,6 +9,10 @@ @menu * Overview:: Brief overview of @command{libred}. +* Constants:: Symbolic constants in @file{<libred.h>}. +* Macros:: Macros in @file{<libred.h>}. +* Functions:: Functions in @file{<libred.h>}. +* Variables:: External variables in @file{<libred.h>}. * Free Software Needs Free Documentation:: Why free documentation is important. * GNU General Public License:: Copying and sharing @command{libred}. @@ -18,6 +22,10 @@ @include chap/overview.texinfo +@include chap/constants.texinfo +@include chap/macros.texinfo +@include chap/functions.texinfo +@include chap/variables.texinfo @include appx/free-software-needs-free-documentation.texinfo diff --git a/doc/man/libred.h.0 b/doc/man/libred.h.0 index 30ef848..e837cb9 100644 --- a/doc/man/libred.h.0 +++ b/doc/man/libred.h.0 @@ -71,7 +71,7 @@ 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 +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. @@ -82,7 +82,7 @@ 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 +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. @@ -93,7 +93,7 @@ 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 +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. @@ -104,7 +104,7 @@ 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 +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. diff --git a/doc/man/libred_get_colour.3 b/doc/man/libred_get_colour.3 index 5220067..c2a951a 100644 --- a/doc/man/libred_get_colour.3 +++ b/doc/man/libred_get_colour.3 @@ -63,8 +63,6 @@ The function may also fail for any reason specified for 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 diff --git a/doc/man/libred_solar_elevation.3 b/doc/man/libred_solar_elevation.3 index b87124a..05a4100 100644 --- a/doc/man/libred_solar_elevation.3 +++ b/doc/man/libred_solar_elevation.3 @@ -22,7 +22,7 @@ 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, not error is thrown if used. +Other values may or may not work, no error is thrown if used. .SH "RETURN VALUE" Upon successful completion, the function sets .B errno |