doxygen: add newline after \file
[blender.git] / source / blender / blenlib / BLI_dial_2d.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  */
16
17 #ifndef __BLI_DIAL_2D_H__
18 #define __BLI_DIAL_2D_H__
19
20 /** \file
21  * \ingroup bli
22  *
23  * \note dials act similar to old rotation based phones and output an angle.
24  *
25  * They just are initialized with the center of the dial and a threshold value as input.
26  *
27  * When the distance of the current position of the dial from the center
28  * exceeds the threshold, this position is used to calculate the initial direction.
29  * After that, the angle from the initial direction is calculated based on
30  * current and previous directions of the digit, and returned to the user.
31  *
32  * Usage examples:
33  *
34  * \code{.c}
35  * float start_position[2] = {0.0f, 0.0f};
36  * float current_position[2];
37  * float threshold = 0.5f;
38  * float angle;
39  * Dial *dial;
40  *
41  * dial = BLI_dial_initialize(start_position, threshold);
42  *
43  * angle = BLI_dial_angle(dial, curent_position);
44  *
45  * MEM_freeN(dial);
46  * \endcode
47  */
48
49 typedef struct Dial Dial;
50
51 Dial *BLI_dial_initialize(const float start_position[2], float threshold);
52
53 float BLI_dial_angle(Dial *dial, const float current_position[2]);
54
55 #endif  /* __BLI_DIAL_2D_H__ */