aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Manual/en/BH_Color.pod314
-rw-r--r--doc/Manual/en/Makefile2
-rw-r--r--doc/Manual/ru/BH_Color.pod319
-rw-r--r--doc/Manual/ru/Makefile2
4 files changed, 637 insertions, 0 deletions
diff --git a/doc/Manual/en/BH_Color.pod b/doc/Manual/en/BH_Color.pod
new file mode 100644
index 0000000..99e3b64
--- /dev/null
+++ b/doc/Manual/en/BH_Color.pod
@@ -0,0 +1,314 @@
+=encoding UTF-8
+
+
+=head1 NAME
+
+BH_Color - color manipulation utility
+
+
+=head1 SYNTAX
+
+ #include <BH/Math/Box3f.h>
+
+ cc prog.c -o prog -lbh
+
+
+=head1 DESCRIPTION
+
+The BH_Color module provides mechanism for color representation and translation
+between different color spaces color spaces (RGB, HSL and HSV). Additionally,
+this module provides mechanism for blending two colors.
+
+
+=head1 NOTES
+
+Internally, color is stored in four 16-bit integers.
+
+When converting between RGB and HSV/HSL there is ~0.009% error. While this is
+not an issue, if you are using 8-bit RGB value, this may become a problem for
+the 16-bit RGB values (not every RGB value can be represented in unique HSV/HSL
+value). If you need this kind of precision, then this module is not for you.
+
+Almost all color blending modes work like in other software packages. The
+exception is I<BH_COLOR_MODE_SOFT_LIGHT>. This library opted-in for the Pegtop's
+version of the formula (which might yield different results). This might be an
+issue if you are trying to implement standard complient SVG or PDF renderer.
+
+The I<BH_COLOR_MODE_HUE>, I<BH_COLOR_MODE_SATURATION>, I<BH_COLOR_MODE_COLOR>
+and I<BH_COLOR_MODE_LUMINOSITY> are implemented in HSL color space.
+
+
+=head1 API CALLS
+
+
+=head2 BH_ColorRGBA8
+
+ void BH_ColorRGBA8(const BH_Color *color,
+ uint8_t *r,
+ uint8_t *g,
+ uint8_t *b,
+ uint8_t *a);
+
+Gets 8-bit RGBA representation of the I<color>.
+
+Parameters I<r>, I<g>, I<b>, I<a> represent color components in RGB color space.
+
+
+=head2 BH_ColorRGBA16
+
+ void BH_ColorRGBA16(const BH_Color *color,
+ uint16_t *r,
+ uint16_t *g,
+ uint16_t *b,
+ uint16_t *a);
+
+Gets 16-bit RGBA representation of the I<color>.
+
+Parameters I<r>, I<g>, I<b>, I<a> represent color components in RGB color space.
+
+
+=head2 BH_ColorRGBAf
+
+ void BH_ColorRGBAf(const BH_Color *color,
+ float *r,
+ float *g,
+ float *b,
+ float *a);
+
+Gets floating-point RGBA representation of the I<color>.
+
+Parameters I<r>, I<g>, I<b>, I<a> represent color components in RGB color space.
+
+=head2 BH_ColorSetRGBA8
+
+ void BH_ColorSetRGBA8(BH_Color *color,
+ uint8_t r,
+ uint8_t g,
+ uint8_t b,
+ uint8_t a);
+
+Sets 8-bit I<r>, I<g>, I<b>, I<a> components of the color.
+
+
+=head2 BH_ColorSetRGBA16
+
+ void BH_ColorSetRGBA16(BH_Color *color,
+ uint16_t r,
+ uint16_t g,
+ uint16_t b,
+ uint16_t a);
+
+Sets 16-bit I<r>, I<g>, I<b>, I<a> components of the color.
+
+
+=head2 BH_ColorSetRGBAf
+
+ void BH_ColorSetRGBAf(BH_Color *color,
+ float r,
+ float g,
+ float b,
+ float a);
+
+Sets floating-point I<r>, I<g>, I<b>, I<a> components of the color.
+
+
+=head2 BH_ColorHSVAf
+
+ void BH_ColorHSVAf(const BH_Color *color,
+ float *h,
+ float *s,
+ float *v,
+ float *a);
+
+Gets floating-point HSV representation of the I<color>.
+
+Parameters I<h>, I<s>, I<v>, I<a> represent color components in HSV color space.
+
+
+=head2 BH_ColorSetHSVAf
+
+ void BH_ColorSetHSVAf(BH_Color *color,
+ float h,
+ float s,
+ float v,
+ float a);
+
+Sets floating-point I<h>, I<s>, I<v>, I<a> components of the color.
+
+
+=head2 BH_ColorHSLAf
+
+ void BH_ColorHSLAf(const BH_Color *color,
+ float *h,
+ float *s,
+ float *l,
+ float *a);
+
+Gets floating-point HSL representation of the I<color>.
+
+Parameters I<h>, I<s>, I<l>, I<a> represent color components in HSV color space.
+
+
+=head2 BH_ColorSetHSLAf
+
+ void BH_ColorSetHSLAf(BH_Color *color,
+ float h,
+ float s,
+ float l,
+ float a);
+
+Sets floating-point I<h>, I<s>, I<l>, I<a> components of the color.
+
+
+=head2 BH_ColorToRGBA
+
+ void BH_ColorToRGBA(const BH_Color *color,
+ BH_Color *out);
+
+Converts I<color> to RGB color space.
+
+
+=head2 BH_ColorToHSVA
+
+ void BH_ColorToHSVA(const BH_Color *color,
+ BH_Color *out);
+
+Converts I<color> to HSV color space.
+
+
+=head2 BH_ColorToHSLA
+
+ void BH_ColorToHSLA(const BH_Color *color,
+ BH_Color *out);
+
+Converts I<color> to HSL color space.
+
+
+=head2 BH_ColorBlend
+
+ void BH_ColorBlend(const BH_Color *foreground,
+ const BH_Color *background,
+ int mode,
+ BH_Color *dest);
+
+Blends I<foreground> and I<background> color, using specified blending I<mode>.
+
+The following modes can be used:
+
+=over
+
+=item B<BH_COLOR_MODE_NORMAL>
+
+ r = f
+
+=item B<BH_COLOR_MODE_MULTIPLY>
+
+ r = f * b
+
+=item B<BH_COLOR_MODE_SCREEN>
+
+ r = 1 - (1 - f) * (1 - b)
+
+=item B<BH_COLOR_MODE_OVERLAY>
+
+ r = HardLight(b, f)
+
+=item B<BH_COLOR_MODE_DARKEN>
+
+ r = min(f, b)
+
+=item B<BH_COLOR_MODE_LIGHTEN>
+
+ r = max(f, b)
+
+=item B<BH_COLOR_MODE_COLOR_DODGE>
+
+ r = min(1, b / (1 - f))
+
+=item B<BH_COLOR_MODE_COLOR_BURN>
+
+ r = 1 - min(1, (1 - b) / f)
+
+=item B<BH_COLOR_MODE_LINEAR_DODGE>
+
+ r = f + b
+
+=item B<BH_COLOR_MODE_LINEAR_BURN>
+
+ r = f + b - 1
+
+=item B<BH_COLOR_MODE_HARD_LIGHT>
+
+ if (f < 0.5)
+ r = Multipy(2 * f, b)
+ else
+ r = Screen(2 * f - 1, b)
+
+=item B<BH_COLOR_MODE_SOFT_LIGHT>
+
+ r = (1 - 2 * f) * b^2 + 2 * f * b
+
+=item B<BH_COLOR_MODE_DIFFERENCE>
+
+ r = abs(f - b)
+
+=item B<BH_COLOR_MODE_EXCLUSION>
+
+ r = f + b - (2 * f * b)
+
+=item B<BH_COLOR_MODE_HUE>
+
+ r = HSL(H(f), S(b), L(b))
+
+=item B<BH_COLOR_MODE_SATURATION>
+
+ r = HSL(H(b), S(f), L(b))
+
+=item B<BH_COLOR_MODE_COLOR>
+
+ r = HSL(H(f), S(f), L(b))
+
+=item B<BH_COLOR_MODE_LUMINOSITY>
+
+ r = HSL(H(b), S(b), L(f))
+
+=back
+
+
+=head1 STRUCTURES
+
+
+=head2 BH_Color
+
+ typedef struct BH_Color
+ {
+ int type;
+ union
+ {
+ struct
+ {
+ uint16_t r;
+ uint16_t g;
+ uint16_t b;
+ uint16_t a;
+ } rgba;
+ struct
+ {
+ uint16_t h;
+ uint16_t s;
+ uint16_t v;
+ uint16_t a;
+ } hsva;
+ struct
+ {
+ uint16_t h;
+ uint16_t s;
+ uint16_t l;
+ uint16_t a;
+ } hsla;
+ } data;
+ } BH_Color;
+
+=head1 SEE ALSO
+
+L<BH> \ No newline at end of file
diff --git a/doc/Manual/en/Makefile b/doc/Manual/en/Makefile
index c42065a..6175844 100644
--- a/doc/Manual/en/Makefile
+++ b/doc/Manual/en/Makefile
@@ -5,6 +5,7 @@ HTMLS = BH_Algo.html \
BH_Args.html \
BH_Box2f.html \
BH_Box3f.html \
+ BH_Color.html \
BH_Hashmap.html \
BH_IO.html \
BH_Line.html \
@@ -31,6 +32,7 @@ MANS = BH_Algo.3 \
BH_Args.3 \
BH_Box2f.3 \
BH_Box3f.3 \
+ BH_Color.3 \
BH_Hashmap.3 \
BH_IO.3 \
BH_Line.3 \
diff --git a/doc/Manual/ru/BH_Color.pod b/doc/Manual/ru/BH_Color.pod
new file mode 100644
index 0000000..10d0492
--- /dev/null
+++ b/doc/Manual/ru/BH_Color.pod
@@ -0,0 +1,319 @@
+=encoding UTF-8
+
+
+=head1 НАИМЕНОВАНИЕ
+
+BH_Color - утилиты для работы с цветом
+
+
+=head1 СИНТАКСИС
+
+ #include <BH/Math/Box3f.h>
+
+ cc prog.c -o prog -lbh
+
+
+=head1 ОПИСАНИЕ
+
+Модуль BH_Color предоставляет механизм для представления цвета и трансляции
+между различными цветовыми пространствами (RGB, HSL и HSV). Кроме того, этот
+модуль предоставляет механизм для смешивания двух цветов.
+
+
+=head1 ЗАМЕТКИ
+
+Внутренне, цвет хранится в четырех 16-разрядных целых числах.
+
+При преобразовании между RGB и HSV/HSL возникает ошибка ~0,009%. Это не является
+проблемой, если вы используете 8-битные RGB значения. Это может стать проблемой
+если вы используете 16-битные значения RGB (не каждое значение RGB сможет быть
+представлено в уникальном значении HSV/HSL). Если вам нужна такая точность, то
+этот модуль не для вас.
+
+Почти все режимы смешивания цветов работают так же, как и в других программных
+пакетах. Исключением является I<BH_COLOR_MODE_SOFT_LIGHT>. Эта библиотека
+использует Pegtop весию формулы (которая может привести к другому результату).
+Это может быть проблемой, если вы пытаетесь реализовать стандартный рендеринг
+для форматов SVG или PDF.
+
+I<BH_COLOR_MODE_HUE>, I<BH_COLOR_MODE_SATURATION>, I<BH_COLOR_MODE_COLOR>
+и I<BH_COLOR_MODE_LUMINOSITY> реализованы в цветовом пространстве HSL.
+
+
+=head1 API ВЫЗОВЫ
+
+
+=head2 BH_ColorRGBA8
+
+ void BH_ColorRGBA8(const BH_Color *color,
+ uint8_t *r,
+ uint8_t *g,
+ uint8_t *b,
+ uint8_t *a);
+
+Возвращает 8-битное RGB представление цвета I<color>.
+
+Параметры I<r>, I<g>, I<b>, I<a> представляю компоненты цвета в RGB.
+
+
+=head2 BH_ColorRGBA16
+
+ void BH_ColorRGBA16(const BH_Color *color,
+ uint16_t *r,
+ uint16_t *g,
+ uint16_t *b,
+ uint16_t *a);
+
+Возвращает 16-битное RGB представление цвета I<color>.
+
+Параметры I<r>, I<g>, I<b>, I<a> представляют компоненты цвета в RGB.
+
+
+
+=head2 BH_ColorRGBAf
+
+ void BH_ColorRGBAf(const BH_Color *color,
+ float *r,
+ float *g,
+ float *b,
+ float *a);
+
+Возвращает вещественное RGB представление цвета I<color>.
+
+Параметры I<r>, I<g>, I<b>, I<a> представляют компоненты цвета в RGB.
+
+
+=head2 BH_ColorSetRGBA8
+
+ void BH_ColorSetRGBA8(BH_Color *color,
+ uint8_t r,
+ uint8_t g,
+ uint8_t b,
+ uint8_t a);
+
+Устанавливает 8-битные компонеты I<r>, I<g>, I<b>, I<a> цвета.
+
+
+=head2 BH_ColorSetRGBA16
+
+ void BH_ColorSetRGBA16(BH_Color *color,
+ uint16_t r,
+ uint16_t g,
+ uint16_t b,
+ uint16_t a);
+
+Устанавливает 16-битные компонеты I<r>, I<g>, I<b>, I<a> цвета.
+
+
+=head2 BH_ColorSetRGBAf
+
+ void BH_ColorSetRGBAf(BH_Color *color,
+ float r,
+ float g,
+ float b,
+ float a);
+
+Устанавливает вещественные компонеты I<r>, I<g>, I<b>, I<a> цвета.
+
+
+=head2 BH_ColorHSVAf
+
+ void BH_ColorHSVAf(const BH_Color *color,
+ float *h,
+ float *s,
+ float *v,
+ float *a);
+
+Возвращает вещественное HSV представление цвета I<color>.
+
+Параметры I<h>, I<s>, I<v>, I<a> представляют компоненты цвета в RGB.
+
+
+=head2 BH_ColorSetHSVAf
+
+ void BH_ColorSetHSVAf(BH_Color *color,
+ float h,
+ float s,
+ float v,
+ float a);
+
+Устанавливает вещественные компонеты I<h>, I<s>, I<v>, I<a> цвета.
+
+
+=head2 BH_ColorHSLAf
+
+ void BH_ColorHSLAf(const BH_Color *color,
+ float *h,
+ float *s,
+ float *l,
+ float *a);
+
+Возвращает вещественное HSL представление цвета I<color>.
+
+Параметры I<h>, I<s>, I<l>, I<a> представляют компоненты цвета в RGB.
+
+
+=head2 BH_ColorSetHSLAf
+
+ void BH_ColorSetHSLAf(BH_Color *color,
+ float h,
+ float s,
+ float l,
+ float a);
+
+Устанавливает вещественные компонеты I<h>, I<s>, I<l>, I<a> цвета.
+
+
+=head2 BH_ColorToRGBA
+
+ void BH_ColorToRGBA(const BH_Color *color,
+ BH_Color *out);
+
+Преобразует цвет I<color> в цветовое представление RGB.
+
+
+=head2 BH_ColorToHSVA
+
+ void BH_ColorToHSVA(const BH_Color *color,
+ BH_Color *out);
+
+Преобразует цвет I<color> в цветовое представление HSV.
+
+
+=head2 BH_ColorToHSLA
+
+ void BH_ColorToHSLA(const BH_Color *color,
+ BH_Color *out);
+
+Преобразует цвет I<color> в цветовое представление HSL.
+
+
+=head2 BH_ColorBlend
+
+ void BH_ColorBlend(const BH_Color *foreground,
+ const BH_Color *background,
+ int mode,
+ BH_Color *dest);
+
+Смешивает цвета I<foreground> и I<background>, используя указанный режим
+смешивания I<mode>.
+
+Могут использоваться следующие режимы:
+
+=over
+
+=item B<BH_COLOR_MODE_NORMAL>
+
+ r = f
+
+=item B<BH_COLOR_MODE_MULTIPLY>
+
+ r = f * b
+
+=item B<BH_COLOR_MODE_SCREEN>
+
+ r = 1 - (1 - f) * (1 - b)
+
+=item B<BH_COLOR_MODE_OVERLAY>
+
+ r = HardLight(b, f)
+
+=item B<BH_COLOR_MODE_DARKEN>
+
+ r = min(f, b)
+
+=item B<BH_COLOR_MODE_LIGHTEN>
+
+ r = max(f, b)
+
+=item B<BH_COLOR_MODE_COLOR_DODGE>
+
+ r = min(1, b / (1 - f))
+
+=item B<BH_COLOR_MODE_COLOR_BURN>
+
+ r = 1 - min(1, (1 - b) / f)
+
+=item B<BH_COLOR_MODE_LINEAR_DODGE>
+
+ r = f + b
+
+=item B<BH_COLOR_MODE_LINEAR_BURN>
+
+ r = f + b - 1
+
+=item B<BH_COLOR_MODE_HARD_LIGHT>
+
+ if (f < 0.5)
+ r = Multipy(2 * f, b)
+ else
+ r = Screen(2 * f - 1, b)
+
+=item B<BH_COLOR_MODE_SOFT_LIGHT>
+
+ r = (1 - 2 * f) * b^2 + 2 * f * b
+
+=item B<BH_COLOR_MODE_DIFFERENCE>
+
+ r = abs(f - b)
+
+=item B<BH_COLOR_MODE_EXCLUSION>
+
+ r = f + b - (2 * f * b)
+
+=item B<BH_COLOR_MODE_HUE>
+
+ r = HSL(H(f), S(b), L(b))
+
+=item B<BH_COLOR_MODE_SATURATION>
+
+ r = HSL(H(b), S(f), L(b))
+
+=item B<BH_COLOR_MODE_COLOR>
+
+ r = HSL(H(f), S(f), L(b))
+
+=item B<BH_COLOR_MODE_LUMINOSITY>
+
+ r = HSL(H(b), S(b), L(f))
+
+=back
+
+
+=head1 СТРУКТУРЫ
+
+
+=head2 BH_Color
+
+ typedef struct BH_Color
+ {
+ int type;
+ union
+ {
+ struct
+ {
+ uint16_t r;
+ uint16_t g;
+ uint16_t b;
+ uint16_t a;
+ } rgba;
+ struct
+ {
+ uint16_t h;
+ uint16_t s;
+ uint16_t v;
+ uint16_t a;
+ } hsva;
+ struct
+ {
+ uint16_t h;
+ uint16_t s;
+ uint16_t l;
+ uint16_t a;
+ } hsla;
+ } data;
+ } BH_Color;
+
+=head1 СМ. ТАКЖЕ
+
+L<BH> \ No newline at end of file
diff --git a/doc/Manual/ru/Makefile b/doc/Manual/ru/Makefile
index c42065a..6175844 100644
--- a/doc/Manual/ru/Makefile
+++ b/doc/Manual/ru/Makefile
@@ -5,6 +5,7 @@ HTMLS = BH_Algo.html \
BH_Args.html \
BH_Box2f.html \
BH_Box3f.html \
+ BH_Color.html \
BH_Hashmap.html \
BH_IO.html \
BH_Line.html \
@@ -31,6 +32,7 @@ MANS = BH_Algo.3 \
BH_Args.3 \
BH_Box2f.3 \
BH_Box3f.3 \
+ BH_Color.3 \
BH_Hashmap.3 \
BH_IO.3 \
BH_Line.3 \
generated by cgit v1.2.3 (git 2.39.1) at 2025-12-01 02:21:56 +0000