path: root/src/common.h

/* redshift-ng - Automatically adjust display colour temperature according the Sun
 * 
 * Copyright (c) 2009-2018        Jon Lund Steffensen <jonlst@gmail.com>
 * Copyright (c) 2014-2016, 2025  Mattias Andrée <m@maandree.se>
 * 
 * redshift-ng is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * redshift-ng is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with redshift-ng.  If not, see <http://www.gnu.org/licenses/>.
 */
#ifndef REDSHIFT_COMMON_H
#define REDSHIFT_COMMON_H

#include <libsimple.h>
#include <libsimple-arg.h>

#ifndef WINDOWS
# if defined(__WIN32__) || defined(_WIN32)
#  define WINDOWS
# endif
#endif

#include <sys/stat.h>
#include <sys/types.h>
#include <ctype.h>
#include <dirent.h>
#include <errno.h>
#include <fcntl.h>
#include <inttypes.h>
#include <limits.h>
#include <locale.h>
#include <math.h>
#include <signal.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <unistd.h>
#ifdef _POSIX_TIMERS
# include <sys/time.h>
#endif
#ifdef WINDOWS
# include <windows.h>
# define localtime_r(T, TM) localtime_s((TM), (T))
#else
# include <pwd.h>
# include <time.h>
#endif

#include <libred.h>


#ifdef ENABLE_NLS
# include <libintl.h>
#else
# define gettext(s) s
#endif

/**
 * List for translation, and translate in place
 * 
 * @param   s:string-literal  Translatable string
 * @return  :const char *     Translation of `s`
 */
#define _(s) gettext(s)

/**
 * List for translation without translating in place
 *
 * @param   s:string-literal  Translatable string
 * @return  :string-literal   `s` as is
 */
#define N_(s) s


#if defined(__clang__)
# pragma clang diagnostic ignored "-Wunsafe-buffer-usage" /* broken in clang 19.1.7 */
#elif defined(__GNUC__)
# pragma GCC diagnostic ignored "-Wunsuffixed-float-constants"
#endif


#if defined(__GNUC__)
# define GCC_ONLY(...) __VA_ARGS__
#else
# define GCC_ONLY(...)
#endif


/**
 * Truncate a value into a closed range
 * 
 * @param   LO  The lower bound
 * @param   X   The value to truncated
 * @param   UP  The upper bound
 * @return      `X` truncated such that it is at least `LO` and at most `UP`
 */
#define CLAMP(LO, X, UP)  (((LO) > (X)) ? (LO) : (((X) < (UP)) ? (X) : (UP)))

/**
 * Check whether a value is within a closed range
 *
 * @param   LO    The lower bound
 * @param   X     The value to check
 * @param   UP    The upper bound
 * @return  :int  1 if `X` is within [`LO`, `UP`], 0 otherwise
 */
#define WITHIN(LO, X, UP)  ((LO) <= (X) && (X) <= (UP))

/**
 * Check whether a value is within a bounded, open range
 *
 * @param   LO    The lower bound
 * @param   X     The value to check
 * @param   UP    The upper bound
 * @return  :int  1 if `X` is within (`LO`, `UP`), 0 otherwise
 */
#define BETWEEN(LO, X, UP)  ((LO) < (X) && (X) < (UP))


/**
 * Symbol used to delimit paths in environment
 * variables listing multiple paths
 */
#ifdef WINDOWS
# define PATH_DELIMITER ';'
#else
# define PATH_DELIMITER ':'
#endif

/**
 * The number of seconds in a day
 */
#define ONE_DAY  ((time_t)(24L * 60L * 60L))


/**
 * Minimum valid latitude
 */
#define MIN_LATITUDE  -90.0

/**
 * Maximum valid latitude
 */
#define MAX_LATITUDE  90.0

/**
 * Minimum valid longitude
 */
#define MIN_LONGITUDE  -180.0

/**
 * Maximum valid longitude
 */
#define MAX_LONGITUDE  180.0

/**
 * Minimum allowed colour temperature
 */
#define MIN_TEMPERATURE  ((unsigned long int)LIBRED_LOWEST_TEMPERATURE)

/**
 * Maximum allowed colour temperature
 */
#define MAX_TEMPERATURE  ULONG_MAX

/**
 * Minimum allowed whitepoint brightness
 */
#define MIN_BRIGHTNESS  0.1

/**
 * Maximum allowed whitepoint brightness
 */
#define MAX_BRIGHTNESS  1.0

/**
 * Minimum allowed gamma
 */
#define MIN_GAMMA  0.1

/**
 * Maximum allowed gamma
 */
#define MAX_GAMMA  10.0


/**
 * The colour temperature corresponding to no effect
 */
#define NEUTRAL_TEMPERATURE  6500UL

/**
 * The whitepoint brightness corresponding to
 * full brightness (no effect)
 */
#define NEUTRAL_BRIGHTNESS  1.0

/**
 * The gamma corresponding to no effect (linear output level curve)
 */
#define NEUTRAL_GAMMA  1.0


/**
 * Default daytime colour temperature
 */
#define DEFAULT_DAY_TEMPERATURE  6500UL

/**
 * Default night colour temperature
 */
#define DEFAULT_NIGHT_TEMPERATURE  4500UL

/**
 * Default daytime whitepoint brightness level
 */
#define DEFAULT_DAY_BRIGHTNESS  NEUTRAL_BRIGHTNESS

/**
 * Default night whitepoint brightness level
 */
#define DEFAULT_NIGHT_BRIGHTNESS  NEUTRAL_BRIGHTNESS

/**
 * Default daytime gamma value
 */
#define DEFAULT_DAY_GAMMA  NEUTRAL_GAMMA

/**
 * Default night gamma value
 */
#define DEFAULT_NIGHT_GAMMA  NEUTRAL_GAMMA

/**
 * The solar elevation, in degrees, that marks the
 * threshold to daytime
 */
#define DEFAULT_HIGH_ELEVATION  3.0

/**
 * The solar elevation, in degrees, that marks the
 * threshold to night
 */
#define DEFAULT_LOW_ELEVATION  LIBRED_SOLAR_ELEVATION_CIVIL_DUSK_DAWN


/**
 * Initialiser for `struct colour_setting`
 * 
 * Sets all values to their neutral values (no effects applied)
 */
#define COLOUR_SETTING_NEUTRAL\
	((struct colour_setting){\
		NEUTRAL_TEMPERATURE,\
		NEUTRAL_BRIGHTNESS,\
		{NEUTRAL_GAMMA, NEUTRAL_GAMMA, NEUTRAL_GAMMA}\
	})


/**
 * State of an adjustment method
 * 
 * Each method has their own definition of this structure
 */
typedef struct gamma_state GAMMA_STATE;

/**
 * State of a location provider
 * 
 * Each provider has their own definition of this structure
 */
typedef struct location_state LOCATION_STATE;


enum period {
	PERIOD_NONE = 0,
	PERIOD_DAYTIME,
	PERIOD_NIGHT,
	PERIOD_TRANSITION
};

enum program_mode {
	PROGRAM_MODE_CONTINUAL,
	PROGRAM_MODE_ONE_SHOT,
	PROGRAM_MODE_PRINT,
	PROGRAM_MODE_RESET,
	PROGRAM_MODE_MANUAL
};


/**
 * By what the effects of the application change
 */
enum scheme_type {
	/**
	 * Effects are dependent on the Sun's elevation
	 */
	SOLAR_SCHEME,

	/**
	 * Effects are dependent on the wall clock time
	 */
	CLOCK_SCHEME,

	/**
	 * Effects do not change
	 */
	STATIC_SCHEME
};


/**
 * The sources where an setting was been loaded from
 * 
 * Higher valued sources have higher priority
 * 
 * This is a bitmask `enum`
 */
enum setting_source {
	/**
	 * No setting loaded, default value set
	 */
	SETTING_DEFAULT = 0x00,

	/**
	 * Setting loaded from configuration file
	 */
	SETTING_CONFIGFILE = 0x01,

	/**
	 * Setting loaded from command line arguments
	 */
	SETTING_CMDLINE = 0x02
};


/**
 * Specification for a path that consists of a two parts:
 * the first being defined by the environment, and the
 * seocnd being a static string
 */
struct env_path {
	/**
	 * Whether the environment variable referenced by `.prefix`
	 * should be split at each colon (:) into multiple paths to
	 * test
	 * 
	 * On Windows semicolon (;) is used instead of colon
	 */
	int multidir_env;

	/**
	 * Environment variable to use as the first part of the path
	 * 
	 * `NULL` if the user's home directory should be used
	 * 
	 * The empty string if `.suffix` should be used as is
	 */
	const char *prefix_env;

	/**
	 * The second part of the path
	 */
	const char *suffix;
};


/**
 * Geographical location, using GPS coordinates
 */
struct location {
	/**
	 * Degrees north of the equator
	 */
	double latitude;

	/**
	 * Degrees east of the prime meridian
	 */
	double longitude;
};


/**
 * Colour setting to apply
 */
struct colour_setting {
	/**
	 * Colour temperature, in Kelvin
	 */
	unsigned long int temperature;

	/**
	 * Whitepoint brightness level
	 */
	double brightness;

	/**
	 * Gamma correct, for the each RGB channel
	 * in the order: red, green, and blue
	 */
	double gamma[3];
};


/* Time range.
   Fields are offsets from midnight in seconds. */
struct time_range {
	time_t start;
	time_t end;
};


struct time_period {
	time_t start;
	double day_level;
	double diff_over_duration;
	const struct time_period *next;
};


/* Transition scheme.
   The solar elevations at which the transition begins/ends */
union scheme {
	enum scheme_type type;
	struct {
		enum scheme_type type;
		double high;
		double low;
		double range;
	} elevation;
	struct {
		enum scheme_type type;
		const struct time_period *periods;
		struct time_period periods_array[4];
	} time;
};


struct config_ini_setting {
	struct config_ini_setting *next;
	char *name;
	char *value;
};


struct config_ini_section {
	struct config_ini_section *next;
	char *name;
	struct config_ini_setting *settings;
};


struct config_ini_state {
	struct config_ini_section *sections;
};


struct setting_i {
	enum setting_source source;
	int value;
};

struct setting_lu {
	enum setting_source source;
	unsigned long int value;
};

struct setting_f {
	enum setting_source source;
	double value;
};

struct setting_f3 {
	enum setting_source source;
	double value[3];
};

struct setting_time {
	enum setting_source source;
	time_t value;
};

struct settings {
	/* Path to config file */
	const char *config_file;

	struct config_ini_state config;

	struct {
		struct setting_lu temperature;
		struct setting_f brightness;
		struct setting_f3 gamma;
	} day, night;
	struct setting_i preserve_gamma; /* Whether to preserve gamma ramps if supported by gamma method. */
	struct setting_i use_fade; /* Whether to fade between large skips in colour temperature. */

	struct setting_f elevation_high; /* TODO no cmdline option */
	struct setting_f elevation_low; /* TODO no cmdline option */
	struct {
		struct setting_time start;
		struct setting_time end;
	} dawn, dusk; /* TODO no cmdline option */

	/* Selected gamma method. */
	const struct gamma_method *method;
	/* Arguments for gamma method. */
	char *method_args;

	/* Selected location provider. */
	const struct location_provider *provider;
	/* Arguments for location provider. */
	char *provider_args;

	enum program_mode mode;
	int verbose;
	enum scheme_type scheme_type;
};


/**
 * Adjustment method information and interface
 */
struct gamma_method {
	const char *name;

	/* If true, this method will be tried if none is explicitly chosen. */
	int autostart;

	/* Initialize state. Options can be set between init and start. */
	int (*init)(GAMMA_STATE **state);
	/* Allocate storage and make connections that depend on options. */
	int (*start)(GAMMA_STATE *state, enum program_mode mode);
	/* Free all allocated storage and close connections. */
	void (*free)(GAMMA_STATE *state);

	/* Print help on options for this adjustment method. */
	void (*print_help)(FILE *f);
	/* Set an option key, value-pair */
	int (*set_option)(GAMMA_STATE *state, const char *key, const char *value);

	/* Restore the adjustment to the state before start was called. */
	void (*restore)(GAMMA_STATE *state);
	/* Set a specific colour temperature. */
	int (*set_temperature)(GAMMA_STATE *state, const struct colour_setting *setting, int preserve);
};


/**
 * Location provider information and interface
 */
struct location_provider {
	const char *name;

	/* Initialize state. Options can be set between init and start. */
	int (*init)(LOCATION_STATE **state);
	/* Allocate storage and make connections that depend on options. */
	int (*start)(LOCATION_STATE *state);
	/* Free all allocated storage and close connections. */
	void (*free)(LOCATION_STATE *state);

	/* Print help on options for this location provider. */
	void (*print_help)(FILE *f);
	/* Set an option key, value-pair. */
	int (*set_option)(LOCATION_STATE *state, const char *key, const char *value);

	/* Listen and handle location updates. */
	int (*get_fd)(LOCATION_STATE *state);
	int (*handle)(LOCATION_STATE *state, struct location *location, int *available);
};


/**
 * `NULL` terminated list of adjustment methods
 */
extern const struct gamma_method *gamma_methods[];

/**
 * `NULL` terminated list of location providers
 */
extern const struct location_provider *location_providers[];

/**
 * Set to 1 once the process has received a signal to terminate
 */
extern volatile sig_atomic_t exiting;

/**
 * Set to 1 once the process has received a signal to remove its effect
 */
extern volatile sig_atomic_t disable;

/**
 * The colour settings applied at daytime
 */
extern struct colour_setting day_settings;

/**
 * The colour settings applied at nighttime
 */
extern struct colour_setting night_settings;

/**
 * The colour settings applied at nighttime
 */
extern union scheme scheme;


/* colour.c */

#define LIST_RAMPS_STOP_VALUE_TYPES(X, D)\
	X(u8, uint8_t, UINT8_MAX, 8) D\
	X(u16, uint16_t, UINT16_MAX, 16) D\
	X(u32, uint32_t, UINT32_MAX, 32) D\
	X(u64, uint64_t, UINT64_MAX, 64) D\
	X(float, float, 1, -1) D\
	X(double, double, 1, -2)

#define X(SUFFIX, TYPE, MAX, DEPTH)\
	/**
	 * Fill the gamma ramps
	 * 
	 * @param  gamma_r   The gamma ramp for the red channel
	 * @param  gamma_g   The gamma ramp for the green channel
	 * @param  gamma_b   The gamma ramp for the blue channel
	 * @param  size_r    The number of stops in `gamma_r`
	 * @param  size_g    The number of stops in `gamma_g`
	 * @param  size_b    The number of stops in `gamma_b`
	 * @param  settings  The colour settings to apply (temperature, brightness, gamma)
	 */\
	void fill_ramps_##SUFFIX(TYPE *gamma_r, TYPE *gamma_g, TYPE *gamma_b,\
	                         size_t size_r, size_t size_g, size_t size_b,\
	                         const struct colour_setting *setting)
LIST_RAMPS_STOP_VALUE_TYPES(X, ;);
#undef X


/* config-ini.c */

/**
 * Load the configuration file
 * 
 * @param  state  Output parameter for the configurations
 * @param  path   The path to the configuration file, or `NULL` if the
 *                application should look for it in the default paths
 */
void config_ini_init(struct config_ini_state *state, const char *path);

/**
 * Deallocate the settings loaded
 * from the configurations file
 * 
 * @param  state  The configurations
 */
void config_ini_free(struct config_ini_state *state);

/**
 * Get a section from the configuration file
 * 
 * @param   state  The configurations
 * @param   name   The name of the section
 * @return         The section; `NULL` if missing
 */
GCC_ONLY(__attribute__((__pure__)))
struct config_ini_section *config_ini_get_section(struct config_ini_state *state, const char *name);


/* config.c */

/**
 * Load settings
 * 
 * @param  settings  Output parameter for the settings
 * @param  argc      Number of command line arguments
 * @param  argv      `NULL` terminated list of command line arguments,
 *                   including argument zero
 */
void load_settings(struct settings *settings, int argc, char *argv[]);


/* gamma.c */

void acquire_adjustment_method(struct settings *settings, GAMMA_STATE **method_state_out);


/* location.c */

int get_location(const struct location_provider *provider, LOCATION_STATE *state, int timeout, struct location *loc);

void acquire_location_provider(struct settings *settings, LOCATION_STATE **location_state_out);


/* hooks.c */

/**
 * Run hooks with a signal that the period changed
 * 
 * @param  prev_period  The previous period
 * @param  period       The new current period
 */
void run_period_change_hooks(enum period prev_period, enum period period);


/* signals.c */

/**
 * Install signal handlers for the process
 */
void install_signal_handlers(void);


/* util.c */

/**
 * Remove trailing whitespace
 * 
 * @param   s    The string to trim, will be truncated
 * @param   end  The current end of `s`; will be looked up if `NULL`
 * @return       `s`
 */
char *rtrim(char *s, char *end);

/**
 * Remove leading whitespace
 * 
 * @param   s  The string to trim (will not be modified)
 * @return     `s` with an offset
 */
GCC_ONLY(__attribute__((__warn_unused_result__, __pure__)))
char *ltrim(char *s);

/**
 * Get the user's home directory
 *
 * This function looks up the user's home directory
 * once and caches the result, later calls to this
 * function will use the cached result
 * 
 * @return  The user's home directory; the empty string if not found
 */
const char *get_home(void);

/**
 * Search for a file and open it for reading
 * 
 * @param   path_spec    Specification for the path to try
 * @param   path_out     Output parameter for the found file
 * @param   pathbuf_out  Output parameter for the memory allocation for `*path_out`;
 *                       shall be free(3)d by the caller
 * @return               `FILE` object for the reading the file; `NULL` if not found
 */
FILE *try_path_fopen(const struct env_path *path_spec, const char **path_out, char **pathbuf_out);

/**
 * Search for a directory and open it for reading
 * 
 * @param   path_spec    Specification for the path to try
 * @param   path_out     Output parameter for the found directory
 * @param   pathbuf_out  Output parameter for the memory allocation for `*path_out`;
 *                       shall be free(3)d by the caller
 * @return               `DIR` object for the reading the directory; `NULL` if not found
 */
DIR *try_path_opendir(const struct env_path *path_spec, const char **path_out, char **pathbuf_out);

/**
 * Create a pipe(7) where both ends have `O_NONBLOCK` applied
 * 
 * @param   pipefds  Output parameter for the pipe's file descriptors:
 *                   0) reading file descriptor, and
 *                   1) writing file descriptor
 * @return           0 on success, -1 on failure
 */
int pipe_nonblock(int pipefds[2]);


extern const struct gamma_method dummy_gamma_method;

#ifdef ENABLE_COOPGAMMA
extern const struct gamma_method coopgamma_gamma_method;
#endif

#ifdef ENABLE_RANDR
extern const struct gamma_method randr_gamma_method;
#endif

#ifdef ENABLE_VIDMODE
extern const struct gamma_method vidmode_gamma_method;
#endif

#ifdef ENABLE_DRM
extern const struct gamma_method drm_gamma_method;
#endif

#ifdef ENABLE_QUARTZ
extern const struct gamma_method quartz_gamma_method;
#endif

#ifdef ENABLE_W32GDI
extern const struct gamma_method w32gdi_gamma_method;
#endif


extern const struct location_provider manual_location_provider;

#ifdef ENABLE_GEOCLUE2
extern const struct location_provider geoclue2_location_provider;
#endif

#ifdef ENABLE_CORELOCATION
extern const struct location_provider corelocation_location_provider;
#endif


#endif