Улучшение структуры документации

This commit is contained in:
Andrey Pokidov 2025-02-08 00:47:44 +07:00
parent 72b6690ad6
commit f8f6b07c81
20 changed files with 262 additions and 156 deletions

View file

@ -10,11 +10,13 @@ There are three units of measurement for angles in the library:
The units of measurement of angles are defined with an enumerated type:
```c
typedef enum {
BGC_ANGLE_UNIT_RADIANS = 1,
BGC_ANGLE_UNIT_DEGREES = 2,
BGC_ANGLE_UNIT_TURNS = 3
} BgcAngleUnitEnum;
```
* BGC_ANGLE_UNIT_RADIANS is for measurement of angles in radians
* BGC_ANGLE_UNIT_DEGREES is for measurement of angles in degrees
@ -27,9 +29,9 @@ There are two ranges of normalized angles: a signed range and an unsigned
range.
The unsigned range has no negative values. The unsigned range corresponds:
* [0, 2π) radians
* [0, 360) degrees
* [0, 1) turns
* \[0, 2π) radians
* \[0, 360) degrees
* \[0, 1) turns
The signed range has both positive and negative values. The signed range
corresponds:
@ -39,10 +41,15 @@ corresponds:
The ranges of angles are defined with an enumerated type:
```c
typedef enum {
BGC_ANGLE_RANGE_UNSIGNED = 1,
BGC_ANGLE_RANGE_SIGNED = 2
} BgcAngleRangeEnum;
```
* BGC_ANGLE_RANGE_UNSIGNED is for the unsigned range of values;
* BGC_ANGLE_RANGE_SIGNED is for the signed range of values.
[Back](intro-eng.md)

View file

@ -11,11 +11,13 @@
Единицы измерения углов определены в перечилении:
```c
typedef enum {
BGC_ANGLE_UNIT_RADIANS = 1,
BGC_ANGLE_UNIT_DEGREES = 2,
BGC_ANGLE_UNIT_TURNS = 3
} BgcAngleUnitEnum;
```
* BGC_ANGLE_UNIT_RADIANS для уголов, измеряемых в радианах
* BGC_ANGLE_UNIT_DEGREES для уголов, измеряемых в градусах
@ -30,9 +32,9 @@
(unsigned).
Беззнаковый диапазон не содержит отрицательных значений и соответствует:
* [0, 2π) радиан
* [0, 360) градусов
* [0, 1) оборотов
* \[0, 2π) радиан
* \[0, 360) градусов
* \[0, 1) оборотов
Знаковый диапазон содержит как отрицательные, так и положительные значения.
Знаковый диапазон соответствует:
@ -42,10 +44,14 @@
Диапазоны значений определены перечиляемым типом:
```c
typedef enum {
BGC_ANGLE_RANGE_UNSIGNED = 1,
BGC_ANGLE_RANGE_SIGNED = 2
} BgcAngleRangeEnum;
```
* BGC_ANGLE_RANGE_UNSIGNED для беззнакового диапазона значений;
* BGC_ANGLE_RANGE_SIGNED для знакового диапазона значений.
[Назад](intro-rus.md)

View file

@ -1,6 +1,8 @@
# Naming
# Basic Geomtric Computations
## Prefixes
## Naming
### Prefixes
The library uses prefixes in names of types, constants and functions.
@ -15,7 +17,7 @@ BGC_TWO_PI_FP64.
The functions have prefix in the form **bgc_**. For example:
bgc_versor_combine_fp32, bgc_matrix3x3_subtract_fp32.
## Suffixes
### Suffixes
Suffixs of type ends the names of constats, types and functions of the library.
The library uses two types of floating point numbers: **float** and **double**
@ -49,6 +51,8 @@ the type suffix: bgc_vector3_reset_fp64, bgc_radians_normalize_fp64.
## Entities
- Vectors 2D and 3D
- [Versors](./versor-eng.md)
- [Vectors 2D](vector-eng.md)
- Vectors 3D
- [Quaternions](quaternion-eng.md)
- [Versors](versor-eng.md)

View file

@ -1,6 +1,8 @@
# Названия
# Библиотека базовых геометрических вычислений
## Префиксы
## Особенности наименования
### Префиксы
Библиотека использует префиксы в названиях типов, констант и функций.
@ -16,7 +18,7 @@ BGC_TWO_PI_FP64.
Функции имеют префикс в виде **bgc_**, например: bgc_versor_combine_fp32,
bgc_matrix3x3_subtract_fp64.
## Cуффиксы
### Cуффиксы
Названия констант, типов и функций оканчиваются суффиксом, указывающим на
базовый тип. Библиотека использует два типа чисел с плавающей запятой:
@ -48,7 +50,9 @@ bcg_vector2_get_modulus_fp32, bgc_radians_to_degrees_fp32.
Функции, которые работают с данными типа **double** имеют суффикс **_fp64**:
bgc_vector3_reset_fp64, bgc_radians_normalize_fp64.
## Contents
## Сущности
- 2D и 3D векторы
- [Versors](./versor-rus.md)
- [2D векторы](vector-rus.md)
- 3D векторы
- [Кватернионы](quaternion-rus.md)
- [Версоры](versor-rus.md)

View file

@ -53,9 +53,11 @@ General-purpose quaternions can also be used to represent rotations in three-dim
```
Fields:
- s0 is the real part of the versor.
- x1, x2, x3 - Imaginary components of the versor.
- s0 is the real part of the quaternion.
- x1, x2, x3 - Imaginary components of the quaternion.
The versor fields are declared as const so that the developer uses the library functions to work with versors, and does not change them directly.
The quaternion fields are free to be changed by the developer using the library.
[Back](intro-eng.md)

View file

@ -52,9 +52,11 @@ q = w + ix + jy + kz
```
Поля:
- s0 - это вещественная часть версора.
- x1, x2, x3 - Мнимые компоненты версора.
- s0 - это вещественная часть кватерниона.
- x1, x2, x3 - Мнимые компоненты кватерниона.
Поля версоров объявлены как const, чтобы разработчик использовал функции библиотеки для работы с версорами, а не изменял их напрямую.
Поля кватернионов разработчик, использующий библиотеку, может менять свободно.
[Назад](intro-rus.md)

View file

@ -1,19 +1,12 @@
# Two dimensional vectors
There are two types for two dimensional vectors:
- BgcVector2FP32 for single precision vectors
- BgcVector2FP64 for double precision vectors
There are two types of 2D vectors in the library:
- **BgcVector2FP32** - vector using single-precision floating-point numbers
- **BgcVector2FP64** - vector using double-precision floating-point numbers
Vectors of BgFP32Vecto2 type use **float** (binary32 of IEEE 754) type to store
coordinate values.
Vectors of BgFP64Vecto2 type use **double** (binary64 of IEEE 754) type to store
coordinate values.
The both types are structures with two fields: **x1** and **x2**
The definition of the types:
Structure definitions:
```c
typedef struct
{
float x1, x2;
@ -23,4 +16,9 @@ The definition of the types:
{
double x1, x2;
} BgcVector2FP64;
```
## Functions
[Back](intro-eng.md)

View file

@ -1,18 +1,12 @@
# Двумерные векторы
# Двумерные векторы векторы
В библиотеке есть две версии вектора:
- BgcVector2FP32 - вектор одинарной точности
- BgcVector2FP64 - вектор двойной точности
В библиотеке есть два типа двумерных векторов:
- **BgcVector2FP32** - вектор с использованием чисел с плавающей запятой одинарной точности
- **BgcVector2FP64** - вектор с использованием чисел с плавающей запятой двойной точности
Векторы типа BgcVector2FP32 для хранения координат использует тип **float** (тип
binary32 стандарта IEEE 754).
Векторы BgcVector2FP64 используют тип **double** (тип binary64 стандарта IEEE 754).
Оба типа представляют собой структуры с двумя полями: **x1** и **x2**.
Определение типов:
Определения структур:
```c
typedef struct
{
float x1, x2;
@ -22,47 +16,11 @@ binary32 стандарта IEEE 754).
{
double x1, x2;
} BgcVector2FP64;
```
Операции:
- сбос состояния
- указание координат
- копирование
- обмен
- конвертация типа
- получение обратного вектора
## Функции
### Сброс состояния
Для сброса координат в нулевое значение предлагаются следующие функции:
inline void bgc_vector2_reset_fp32(BgcVector2FP32* vector);
inline void bgc_vector2_reset_fp64(BgcVector2FP64* vector);
Каждая из данных функции эквивалентна следующим строкам кода:
vector->x1 = 0;
vector->x2 = 0;
В данные функции не следует передавать некорректные указатели. Значение NULL (0)
в качестве параметра также считается некорректным.
Пример применения:
#include <stdio.h>
#include <basic-geometry.h>
int main()
{
BgcVector2FP32 my_vector;
bgc_vector2_reset_fp32(&my_vector);
printf("x1 = %f, x2 = %f\n", my_vector.x1, my_vector.x2);
return 0;
}
### Указание координат
### Указание координат двумерного вектора
Для прямого указания координат предлагаются следующие две функции:
@ -174,3 +132,5 @@ binary32 стандарта IEEE 754).
Тем не менее, в библиотеке есть функции, которые позволяют преобразовать данные
одного типа в данные другого типа.
[Назад](intro-rus.md)

44
docs/vector2/reset-eng.md Normal file
View file

@ -0,0 +1,44 @@
# Resetting the state of a 2D vector
These functions set all coordinates of 2D vectors to 0.
Function for **BgcVector2FP32**:
```c
inline void bgc_vector2_reset_fp32(BgcVector2FP32* vector);
```
Function for **BgcVector2FP64**:
```c
inline void bgc_vector2_reset_fp64(BgcVector2FP64* vector);
```
Each of these functions is equivalent to the following lines of code:
```c
vector->x1 = 0;
vector->x2 = 0;
```
You should not pass invalid pointers to these functions. The NULL (0) value is also considered invalid.
Example of use:
```c
#include <stdio.h>
#include <basic-geometry.h>
int main()
{
BgcVector2FP32 my_vector;
bgc_vector2_reset_fp32(&my_vector);
printf("x1 = %f, x2 = %f\n", my_vector.x1, my_vector.x2);
return 0;
}
```
[Back](../vector2-eng.md)

44
docs/vector2/reset-rus.md Normal file
View file

@ -0,0 +1,44 @@
# Сброс состояния двумерного вектора
Функции устанавливают значение 0 всем координатам двумерных векторов.
Функция для **BgcVector2FP32**:
```c
inline void bgc_vector2_reset_fp32(BgcVector2FP32* vector);
```
Функция для **BgcVector2FP64**:
```c
inline void bgc_vector2_reset_fp64(BgcVector2FP64* vector);
```
Каждая из данных функции эквивалентна следующим строкам кода:
```c
vector->x1 = 0;
vector->x2 = 0;
```
В данные функции не следует передавать некорректные указатели. Значение NULL (0) также считается некорректным.
Пример применения:
```c
#include <stdio.h>
#include <basic-geometry.h>
int main()
{
BgcVector2FP32 my_vector;
bgc_vector2_reset_fp32(&my_vector);
printf("x1 = %f, x2 = %f\n", my_vector.x1, my_vector.x2);
return 0;
}
```
[Назад](../vector2-rus.md)

View file

View file

@ -1,6 +1,6 @@
# Versors
[Quaternions](./quaternion-eng.md) are hypercomplex numbers that have one real component and three imaginary components:
[Quaternions](quaternion-eng.md) are hypercomplex numbers that have one real component and three imaginary components:
q = w + ix + jy + kz
@ -62,8 +62,8 @@ Fields:
## Operation with versors
- [Reset state](./versor-reset-eng.md)
- [Specify component values](./versor-set-values-eng.md)
- [Reset state](versor/reset-eng.md)
- [Specify component values](versor/set-values-eng.md)
- Copy component values
- Swap component values
- Build based on rotation
@ -78,3 +78,5 @@ Fields:
- Rotate vector
- Inverse vector rotation
- Compare
[Back](intro-eng.md)

View file

@ -1,6 +1,6 @@
# Версоры
[Кватернионы](./quaternion-rus.md) - это гиперкомплексные числа, у которых имеется одна действительная компонента и три мнимых компоненты:
[Кватернионы](quaternion-rus.md) - это гиперкомплексные числа, у которых имеется одна действительная компонента и три мнимых компоненты:
q = w + ix + jy + kz, где w - действительная компонена, x, y, z - мнимые компоненты, а i, j, k - мнимые единицы
@ -62,21 +62,12 @@ q = w + ix + jy + kz
- s0 - это вещественная часть версора.
- x1, x2, x3 - Мнимые компоненты версора.
## Операции с версорами
## Функции
- [Сброс состояния](./versor-reset-rus.md)
- [Указание значений компонент](./versor-set-values-rus.md)
- Копирование состояния (копирование значений компонент)
- Обмен состояниями (обмен значениями компонент)
- Построение на основе поворота
- Проверка на отсутствие поворота
- Преобразование типа
- Сокращение поворота
- Инверсия
- Комбинирование
- Получение описание поворота
- Получение матрицы поворота
- Получение матрицы обратного поворота
- Поворот вектора
- Обратный поворот вектора
- Сравнение
| Функция для BgcVersorFP32 | Функция для BgcVersorFP64 |
|:-------------------------------------------------------------:|:-------------------------------------------------------------:|
| [bgc_versor_reset_fp32](versor/reset-rus.md) | [bgc_versor_reset_fp64](versor/reset-rus.md) |
| [bgc_versor_set_values_fp32](versor/set-values-rus.md) | [bgc_versor_set_values_fp64](versor/set-values-rus.md) |
[Назад](intro-rus.md)

View file

@ -1,47 +0,0 @@
# Ôóíêöèè óñòàíàâëèâàùèå çíà÷åíèÿ êîìïîåíåí âåðñîðà
×òîáû óêàçàòü êîíêðåòíûå çíà÷åíèÿ äëÿ êîìïîíåíò âåðñîðà ïðåäóñìîòðåíû ñïåöèàëüíûå ôóíêöèè.
Äëÿ òèïà **BgFP32Versor** ôóíêöèÿ èìååò âèä:
inline void bgc_versor_set_values_fp32(const float s0, const float x1, const float x2, const float x3, BgcVersorFP32* versor);
Äëÿ òèïà **BgFP64Versor** ôóíêöèÿ èìååò âèä:
inline void bgc_versor_set_values_fp64(const double s0, const double x1, const double x2, const double x3, BgcVersorFP64* versor);
Äàííûå ôóíêöèè óñòàíàâëèâàþò çíà÷åíèÿ, ïåðåäàííûå â ïàðàìåòðàõ **s0**, **x1**, **x2** è **x3**, â ñîîòâåòñòâóþùå êîìïîíåíòû âåðñîðà, ïåðåäàííîãî ïî óêàçàòåëþ â ïàðàìåòðå **versor**. Íî åñëè ïîëó÷èâøååñÿ ñîñòîÿíèå íå ÿâëÿåòñÿ íîðìàëèçîâàííûì êâàòåðíèîíîì, òî ôóíêöèè íîðìàëèçóþò âåðñîð.
Ïàðàìåòð **versor** äîëæåí áûòü êîððåêòíûì óêàçàòåëåì, à òàêæå íå äîëæåí áûòü ðàâåí NULL.
Äàííûå ôóíêöèè òàêæå õîðîøî ïîäõîäÿò äëÿ èíèöèàëèçàöèè ñîñòîÿíèÿ ïåðåìåííûõ òèïîâ **BgFP32Versor** è **BgFP64Versor** êàê è ôóíêöèè [bgc_versor_reset_fp32 è bgc_versor_reset_fp64](./versor-reset-eng.md).
Ïðèìåð èñïîëüçîâàíèÿ:
#include <stdio.h>
#include <basic-geometry.h>
int main() {
BgcVersorFP64 versor;
bgc_versor_set_values_fp64(1, 2, 3, 4, &versor);
printf("Versor: (%lf, %lf, %lf, %lf)\n", versor.s0, versor.x1, versor.x2, versor.x3);
return 0;
}
Ðåçóëüòàò:
Versor: (0.182574, 0.365148, 0.547723, 0.730297)
Åñëè â êà÷åñòâå çíà÷åíèé êîìïîíåíò â ôóíêöèþ ïåðåäàòü íóëè, òî âåðñîð, óêàçàòåëü íà êîòîðûé ïåðåäàí â ïàðàìåòðå **versor**, áóäåò óñòàíîâëåí â ñîñòîÿíèå, ñîîòâåòñòâóþùåå îòñóòñòâèþ ïîâîðîòà:
bgc_versor_set_values_fp64(0, 0, 0, 0, &versor);
Ðåçóëüòàò:
Versor: (1.000000, 0.000000, 0.000000, 0.000000)
[Âåðñîðû](./versor-rus.md)

View file

@ -2,20 +2,26 @@
[A versor](./versor-eng.md) that corresponds to no rotation has the following component values:
```
s0 = 1;
x1 = 0;
x2 = 0;
x3 = 0;
```
To set such a state for the versor components, the library has the corresponding functions.
For the **BgFP32Versor** type, the function is:
void bgc_versor_reset_fp32(BgFP32Versor* versor);
```c
inline void bgc_versor_reset_fp32(BgFP32Versor* versor);
```
For the **BgFP64Versor** type, the function is:
void bgc_versor_reset_fp64(BgFP64Versor* versor);
```c
inline void bgc_versor_reset_fp64(BgFP64Versor* versor);
```
The **versor** parameter must be a valid pointer and must not be NULL.
@ -23,6 +29,7 @@ These functions are well suited for initializing the state of variables of the *
Usage example:
```c
#include <stdio.h>
#include <basic-geometry.h>
@ -35,9 +42,12 @@ Usage example:
return 0;
}
```
Result:
```
Versor: (1.000000, 0.000000, 0.000000, 0.000000)
```
[Versors](./versor-eng.md)

View file

@ -2,20 +2,26 @@
[Версор](./versor-rus.md), который соответствует отсутствию поворота, имеет следующие значеия компонент:
```
s0 = 1;
x1 = 0;
x2 = 0;
x3 = 0;
```
Чтобы установить такое состояние для компонент версора, в библиотеке есть соответствующие функции.
Для типа **BgFP32Versor** функция имеет вид:
```c
inline void bgc_versor_reset_fp32(BgFP32Versor* versor);
```
Для типа **BgFP64Versor** функция имеет вид:
```c
inline void bgc_versor_reset_fp64(BgFP64Versor* versor);
```
Параметр **versor** должен быть корректным указателем, а также не должен быть равен NULL.
@ -23,6 +29,7 @@
Пример использования:
```c
#include <stdio.h>
#include <basic-geometry.h>
@ -35,9 +42,12 @@
return 0;
}
```
Результат:
```
Versor: (1.000000, 0.000000, 0.000000, 0.000000)
```
[Версоры](./versor-rus.md)
[Библиотека базовых геометрических вычислений](./intro-rus.md) / [Версоры](./versor-rus.md)

View file

@ -4,11 +4,15 @@ Special functions are provided to specify specific values ??for the versor compo
For the **BgFP32Versor** type, the function has the form:
```c
inline void bgc_versor_set_values_fp32(const float s0, const float x1, const float x2, const float x3, BgcVersorFP32* versor);
```
For the **BgFP64Versor** type, the function has the form:
```c
inline void bgc_versor_set_values_fp64(const double s0, const double x1, const double x2, const double x3, BgcVersorFP64* versor);
```
These functions set the values ??passed in the **s0**, **x1**, **x2**, and **x3** parameters to the corresponding components of the versor passed by pointer in the **versor** parameter. But if the resulting state is not a normalized quaternion, then the functions normalize the versor.
@ -16,7 +20,7 @@ The **versor** parameter must be a valid pointer and must not be NULL.
These functions are also well suited for initializing the state of variables of types **BgFP32Versor** and **BgFP64Versor**, as are the functions [bgc_versor_reset_fp32 and bgc_versor_reset_fp64](./versor-reset-eng.md).
```c
#include <stdio.h>
#include <basic-geometry.h>
@ -29,17 +33,24 @@ These functions are also well suited for initializing the state of variables of
return 0;
}
```
Result:
```
Versor: (0.182574, 0.365148, 0.547723, 0.730297)
```
If zeros are passed to the function as component values, then the versor, the pointer to which is passed in the **versor** parameter, will be set to the state corresponding to the absence of rotation:
```c
bgc_versor_set_values_fp64(0, 0, 0, 0, &versor);
```
Result:
```
Versor: (1.000000, 0.000000, 0.000000, 0.000000)
```
[Versors](./versor-eng.md)

View file

@ -0,0 +1,58 @@
# Функции устанавливащие значения компоенен версора
Чтобы указать конкретные значения для компонент версора предусмотрены специальные функции.
Для типа **BgFP32Versor** функция имеет вид:
```c
inline void bgc_versor_set_values_fp32(const float s0, const float x1, const float x2, const float x3, BgcVersorFP32* versor);
```
Для типа **BgFP64Versor** функция имеет вид:
```c
inline void bgc_versor_set_values_fp64(const double s0, const double x1, const double x2, const double x3, BgcVersorFP64* versor);
```
Данные функции устанавливают значения, переданные в параметрах **s0**, **x1**, **x2** и **x3**, в соответствующе компоненты версора, переданного по указателю в параметре **versor**. Но если получившееся состояние не является нормализованным кватернионом, то функции нормализуют версор.
Параметр **versor** должен быть корректным указателем, а также не должен быть равен NULL.
Данные функции также хорошо подходят для инициализации состояния переменных типов **BgFP32Versor** и **BgFP64Versor** как и функции [bgc_versor_reset_fp32 и bgc_versor_reset_fp64](./versor-reset-eng.md).
Пример использования:
```c
#include <stdio.h>
#include <basic-geometry.h>
int main() {
BgcVersorFP64 versor;
bgc_versor_set_values_fp64(1, 2, 3, 4, &versor);
printf("Versor: (%lf, %lf, %lf, %lf)\n", versor.s0, versor.x1, versor.x2, versor.x3);
return 0;
}
```
Результат:
```
Versor: (0.182574, 0.365148, 0.547723, 0.730297)
```
Если в качестве значений компонент в функцию передать нули, то версор, указатель на который передан в параметре **versor**, будет установлен в состояние, соответствующее отсутствию поворота:
```c
bgc_versor_set_values_fp64(0, 0, 0, 0, &versor);
```
Результат:
```
Versor: (1.000000, 0.000000, 0.000000, 0.000000)
```
[Библиотека базовых геометрических вычислений](./intro-rus.md) / [Версоры](./versor-rus.md)

Binary file not shown.