hal_gfx_matrix4x4.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file hal_gfx_matrix4x4.h
5  * @author BLE Driver Team
6  * @brief Header file containing functions prototypes of Graphics library.
7  *
8  ****************************************************************************************
9  * @attention
10  #####Copyright (c) 2019 GOODIX
11  All rights reserved.
12 
13  Redistribution and use in source and binary forms, with or without
14  modification, are permitted provided that the following conditions are met:
15  * Redistributions of source code must retain the above copyright
16  notice, this list of conditions and the following disclaimer.
17  * Redistributions in binary form must reproduce the above copyright
18  notice, this list of conditions and the following disclaimer in the
19  documentation and/or other materials provided with the distribution.
20  * Neither the name of GOODIX nor the names of its contributors may be used
21  to endorse or promote products derived from this software without
22  specific prior written permission.
23 
24  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  POSSIBILITY OF SUCH DAMAGE.
35  ****************************************************************************************
36  */
37 
38 /** @addtogroup GRAPHICS_SDK Graphics
39  * @{
40  */
41 
42 /** @addtogroup HAL_GFX HAL GFX
43  * @{
44  */
45 
46 /** @defgroup HAL_GFX_MATRIX4X4 GFX MATRIX4X4
47  * @brief Base matrix4x4 Operation.
48  * @{
49  */
50 
51 
52 #ifndef HAL_GFX_MATRIX4X4_H__
53 #define HAL_GFX_MATRIX4X4_H__
54 
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
58 /**
59  * @defgroup HAL_GFX_MATRIX4X4_TYPEDEF Typedefs
60  * @{
61  */
62 typedef float hal_gfx_matrix4x4_t[4][4];/**< Global define matrix4x4 variable. */
63 /** @} */
64 
65 /**
66  * @defgroup HAL_GFX_MATRIX4X4_FUNCTION Functions
67  * @{
68  */
69 /**
70  *****************************************************************************************
71  * @brief Load a 4x4 Identity Matrix
72  *
73  * @param[in] m: Matrix to be loaded
74  *
75  *****************************************************************************************
76  */
77 void hal_gfx_mat4x4_load_identity(hal_gfx_matrix4x4_t m);
78 
79 /**
80  *****************************************************************************************
81  * @brief Multiply two 4x4 matrices
82  *
83  * @param[in] m: Result Matrix
84  * @param[in] m_l: Left operand
85  * @param[in] m_r: Right operand
86  *
87  *****************************************************************************************
88  */
89 void hal_gfx_mat4x4_mul(hal_gfx_matrix4x4_t m,
90  hal_gfx_matrix4x4_t m_l,
91  hal_gfx_matrix4x4_t m_r);
92 
93 /**
94  *****************************************************************************************
95  * @brief Multiply a 4x1 vector with a 4x4 matrix
96  *
97  * @param[in] m: Matrix to be multiplied
98  * @param[in] x: Vector first element
99  * @param[in] y: Vector second element
100  * @param[in] z: Vector third element
101  * @param[in] w: Vector forth element
102  *
103  *****************************************************************************************
104  */
105 void hal_gfx_mat4x4_mul_vec(hal_gfx_matrix4x4_t m, float *x, float *y, float *z, float *w);
106 
107 // ------------------------------------------------------------------------------------
108 // Object Transformation - ModelView Matrix
109 // Object Coordinates to Eye Coordinates
110 // ------------------------------------------------------------------------------------
111 /**
112  *****************************************************************************************
113  * @brief Apply translate transformation
114  *
115  * @param[in] m: Matrix to apply transformation
116  * @param[in] tx: X translation factor
117  * @param[in] ty: Y translation factor
118  * @param[in] tz: Z translation factor
119  *
120  *****************************************************************************************
121  */
122 void hal_gfx_mat4x4_translate(hal_gfx_matrix4x4_t m, float tx, float ty, float tz);
123 
124 /**
125  *****************************************************************************************
126  * @brief Apply scale transformation
127  *
128  * @param[in] m: Matrix to apply transformation
129  * @param[in] sx: X scaling factor
130  * @param[in] sy: Y scaling factor
131  * @param[in] sz: Z scaling factor
132  *
133  *****************************************************************************************
134  */
135 void hal_gfx_mat4x4_scale(hal_gfx_matrix4x4_t m, float sx, float sy, float sz);
136 
137 /**
138  *****************************************************************************************
139  * @brief Apply rotate transformation around X axis
140  *
141  * @param[in] m: Matrix to apply transformation
142  * @param[in] angle_degrees: Angle to rotate in degrees
143  *
144  *****************************************************************************************
145  */
146 void hal_gfx_mat4x4_rotate_X (hal_gfx_matrix4x4_t m, float angle_degrees);
147 
148 /**
149  *****************************************************************************************
150  * @brief Apply rotate transformation around Y axis
151  *
152  * @param[in] m: Matrix to apply transformation
153  * @param[in] angle_degrees: Angle to rotate in degrees
154  *
155  *****************************************************************************************
156  */
157 void hal_gfx_mat4x4_rotate_Y (hal_gfx_matrix4x4_t m, float angle_degrees);
158 
159 /**
160  *****************************************************************************************
161  * @brief Apply rotate transformation around Z axis
162  *
163  * @param[in] m: Matrix to apply transformation
164  * @param[in] angle_degrees: Angle to rotate in degrees
165  *
166  *****************************************************************************************
167  */
168 void hal_gfx_mat4x4_rotate_Z (hal_gfx_matrix4x4_t m, float angle_degrees);
169 
170 // ------------------------------------------------------------------------------------
171 // Scene Transformation/Frustum - Projection Matrix
172 // Eye Coordinates to Clip Coordinates
173 // ------------------------------------------------------------------------------------
174 /**
175  *****************************************************************************************
176  * @brief Set up a perspective projection matrix
177  *
178  * @param[in] m: A 4x4 Matrix
179  * @param[in] fovy_degrees: Field of View in degrees
180  * @param[in] aspect: Aspect ratio that determines the field of view in the x direction.
181  * @param[in] nearVal: Distance from the viewer to the near clipping plane (always positive)
182  * @param[in] farVal: Distance from the viewer to the far clipping plane (always positive)
183  *
184  *****************************************************************************************
185  */
186 void hal_gfx_mat4x4_load_perspective(hal_gfx_matrix4x4_t m, float fovy_degrees, float aspect,
187  float nearVal, float farVal);
188 
189 /**
190  *****************************************************************************************
191  * @brief Set up an orthographic projection matrix
192  *
193  * @param[in] m: A 4x4 Matrix
194  * @param[in] left: Left vertical clipping plane
195  * @param[in] right: Right vertical clipping plane
196  * @param[in] bottom: bottom horizontal clipping plane
197  * @param[in] top: Top horizontal clipping plane
198  * @param[in] nearVal: Distance from the viewer to the near clipping plane (always positive)
199  * @param[in] farVal: Distance from the viewer to the far clipping plane (always positive)
200  *
201  *****************************************************************************************
202  */
203 void hal_gfx_mat4x4_load_ortho(hal_gfx_matrix4x4_t m,
204  float left, float right,
205  float bottom, float top,
206  float nearVal, float farVal);
207 
208 /**
209  *****************************************************************************************
210  * @brief Set up a 2D orthographic projection matrix
211  *
212  * @param[in] m: A 4x4 Matrix
213  * @param[in] left: Left vertical clipping plane
214  * @param[in] right: Right vertical clipping plane
215  * @param[in] bottom: bottom horizontal clipping plane
216  * @param[in] top: Top horizontal clipping plane
217  *
218  *****************************************************************************************
219  */
220 void hal_gfx_mat4x4_load_ortho_2d(hal_gfx_matrix4x4_t m,
221  float left, float right,
222  float bottom, float top);
223 
224 // ------------------------------------------------------------------------------------
225 // Clip Coordinates to Window Coordinates
226 // ------------------------------------------------------------------------------------
227 /**
228  *****************************************************************************************
229  * @brief Convenience Function to calculate window coordinates from object coordinates
230  *
231  * @param[in] mvp: Model, View and Projection Matrix
232  * @param[in] x_orig: Window top left X coordinate
233  * @param[in] y_orig: Window top left Y coordinate
234  * @param[in] width: Window width
235  * @param[in] height: Window height
236  * @param[in] nearVal: Distance from the viewer to the near clipping plane (always positive)
237  * @param[in] farVal: Distance from the viewer to the far clipping plane (always positive)
238  * @param[in] x: X object coordinate
239  * @param[in] y: Y object coordinate
240  * @param[in] z: Z object coordinate
241  * @param[in] w: W object coordinate
242 
243  * @return 1 if vertex is outside frustum (should be clipped)
244  *****************************************************************************************
245  */
246 int hal_gfx_mat4x4_obj_to_win_coords(hal_gfx_matrix4x4_t mvp,
247  float x_orig, float y_orig,
248  int width, int height,
249  float nearVal, float farVal,
250  float *x,
251  float *y,
252  float *z,
253  float *w);
254 /** @} */
255 
256 #ifdef __cplusplus
257 }
258 #endif
259 
260 #endif
261 /** @} */
262 /** @} */
263 /** @} */
264 
hal_gfx_mat4x4_rotate_X
void hal_gfx_mat4x4_rotate_X(hal_gfx_matrix4x4_t m, float angle_degrees)
Apply rotate transformation around X axis.
hal_gfx_mat4x4_translate
void hal_gfx_mat4x4_translate(hal_gfx_matrix4x4_t m, float tx, float ty, float tz)
Apply translate transformation.
hal_gfx_mat4x4_load_perspective
void hal_gfx_mat4x4_load_perspective(hal_gfx_matrix4x4_t m, float fovy_degrees, float aspect, float nearVal, float farVal)
Set up a perspective projection matrix.
hal_gfx_mat4x4_load_ortho
void hal_gfx_mat4x4_load_ortho(hal_gfx_matrix4x4_t m, float left, float right, float bottom, float top, float nearVal, float farVal)
Set up an orthographic projection matrix.
hal_gfx_matrix4x4_t
float hal_gfx_matrix4x4_t[4][4]
Global define matrix4x4 variable.
Definition: hal_gfx_matrix4x4.h:62
hal_gfx_mat4x4_mul_vec
void hal_gfx_mat4x4_mul_vec(hal_gfx_matrix4x4_t m, float *x, float *y, float *z, float *w)
Multiply a 4x1 vector with a 4x4 matrix.
hal_gfx_mat4x4_rotate_Y
void hal_gfx_mat4x4_rotate_Y(hal_gfx_matrix4x4_t m, float angle_degrees)
Apply rotate transformation around Y axis.
hal_gfx_mat4x4_mul
void hal_gfx_mat4x4_mul(hal_gfx_matrix4x4_t m, hal_gfx_matrix4x4_t m_l, hal_gfx_matrix4x4_t m_r)
Multiply two 4x4 matrices.
hal_gfx_mat4x4_rotate_Z
void hal_gfx_mat4x4_rotate_Z(hal_gfx_matrix4x4_t m, float angle_degrees)
Apply rotate transformation around Z axis.
hal_gfx_mat4x4_scale
void hal_gfx_mat4x4_scale(hal_gfx_matrix4x4_t m, float sx, float sy, float sz)
Apply scale transformation.
hal_gfx_mat4x4_obj_to_win_coords
int hal_gfx_mat4x4_obj_to_win_coords(hal_gfx_matrix4x4_t mvp, float x_orig, float y_orig, int width, int height, float nearVal, float farVal, float *x, float *y, float *z, float *w)
Convenience Function to calculate window coordinates from object coordinates.
hal_gfx_mat4x4_load_ortho_2d
void hal_gfx_mat4x4_load_ortho_2d(hal_gfx_matrix4x4_t m, float left, float right, float bottom, float top)
Set up a 2D orthographic projection matrix.
hal_gfx_mat4x4_load_identity
void hal_gfx_mat4x4_load_identity(hal_gfx_matrix4x4_t m)
Load a 4x4 Identity Matrix.