@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