microvg  7.0.0
microvg
vg_path.h
Go to the documentation of this file.
1 /*
2  * C
3  *
4  * Copyright 2022-2024 MicroEJ Corp. All rights reserved.
5  * Use of this source code is governed by a BSD-style license that can be found with this software.
6  */
7 
15 #if !defined VG_PATH_H
16 #define VG_PATH_H
17 
18 #if defined __cplusplus
19 extern "C" {
20 #endif
21 
22 #include "vg_configuration.h"
23 
24 #ifdef VG_FEATURE_PATH
25 
26 // -----------------------------------------------------------------------------
27 // Includes
28 // -----------------------------------------------------------------------------
29 
30 #include <sni.h>
31 #include <stddef.h>
32 
33 // -----------------------------------------------------------------------------
34 // Typedefs
35 // -----------------------------------------------------------------------------
36 
37 #if defined(VG_FEATURE_PATH_DUAL_ARRAY) && (VG_FEATURE_PATH == VG_FEATURE_PATH_DUAL_ARRAY)
38 
39 /*
40  * @brief Defines the format of the path's commands.
41  */
42 typedef uint8_t VG_path_command_t;
43 
44 /*
45  * @brief Defines the format of the commands' parameters.
46  */
47 typedef float VG_path_param_t;
48 
49 #endif // VG_FEATURE_PATH_DUAL_ARRAY
50 
51 /*
52  * @brief Map a jbyte array that represents a path
53  */
54 typedef struct MICROVG_PATH_HEADER {
55 #if defined(VG_FEATURE_PATH_SINGLE_ARRAY) && (VG_FEATURE_PATH == VG_FEATURE_PATH_SINGLE_ARRAY)
56  uint32_t data_size; /* data size (without header) */
57 #else // VG_FEATURE_PATH_DUAL_ARRAY
58  size_t param_length;
59  size_t cmd_length;
60  size_t cmd_offset;
61 #endif
62  uint8_t format;
63  uint8_t padding1;
64  uint8_t padding2;
65  uint8_t padding3;
66  float bounds_xmin; /* left */
67  float bounds_xmax; /* right */
68  float bounds_ymin; /* top */
69  float bounds_ymax; /* bottom */
71 
72 // -----------------------------------------------------------------------------
73 // Specific path formatting functions [mandatory]
74 // -----------------------------------------------------------------------------
75 
76 /*
77  * @brief Gets the path's array format used to encode the commands and parameters. This format is stored into the path's
78  * header.
79  *
80  * @return the path's format
81  */
82 uint8_t VG_PATH_get_path_encoder_format(void);
83 
84 /*
85  * @brief Converts the command in destination format.
86  *
87  * @param[in] command: the command to convert
88  *
89  * @return the converted command
90  */
91 uint32_t VG_PATH_convert_path_command(jint command);
92 
93 // -----------------------------------------------------------------------------
94 // Specific path formatting functions [optional]
95 // -----------------------------------------------------------------------------
96 
97 /*
98  * @brief Initializes the path builder.
99  *
100  * The default implementation does nothing.
101  */
102 void VG_PATH_initialize(void);
103 
104 /*
105  * @brief Gets the path's array header size.
106  *
107  * The default implementation returns sizeof(VG_PATH_HEADER_t).
108  *
109  * @return the size in bytes.
110  */
111 uint32_t VG_PATH_get_path_header_size(void);
112 
113 /*
114  * @brief Gets the size to add in the path array to encode the command and its parameters.
115  *
116  * The default implementation uses 32-bit fields for the command and for each data.
117  *
118  * @param[in] command: the command to add.
119  * @param[in] nbParams: the available number of command's parameters
120  *
121  * @return the size to add in the path array.
122  */
123 uint32_t VG_PATH_get_path_command_size(jint command, uint32_t nbParams);
124 
125 /*
126  * @brief Appends the command with zero parameter in the path's array.
127  *
128  * The caller ensures the path's array is large enough to encode the command and its parameters.
129  *
130  * The default implementation uses 32-bit fields for the command and for each data.
131  *
132  * @param[in] path: the path's array
133  * @param[in] array_length: the length of the array
134  * @param[in] cmd: the command to add
135  *
136  * @return LLVG_SUCCESS on a success, or the missing space in the array in bytes
137  *
138  * @see #VG_PATH_get_path_command_size(jint, uint32_t)
139  */
140 uint32_t VG_PATH_append_path_command0(jbyte *path, jint array_length, jint cmd);
141 
142 /*
143  * @brief Appends the command with 1 point parameter in the path's array.
144  *
145  * @param[in] path: the path's array
146  * @param[in] array_length: the length of the array
147  * @param[in] cmd: the command to add
148  * @param[in] x: the command data 1.
149  * @param[in] y: the command data 2.
150  *
151  * @return LLVG_SUCCESS on a success, or the missing space in the array in bytes
152  *
153  * @see #VG_PATH_append_path_command0(jbyte*, uint32_t, jint)
154  */
155 uint32_t VG_PATH_append_path_command1(jbyte *path, jint array_length, jint cmd, jfloat x, jfloat y);
156 
157 /*
158  * @brief Appends the command with 2 points parameter in the path's array.
159  *
160  * @param[in] path: the path's array
161  * @param[in] array_length: the length of the array
162  * @param[in] cmd: the command to add
163  * @param[in] x1: the command data 1.
164  * @param[in] y1: the command data 2.
165  * @param[in] x2: the command data 3.
166  * @param[in] y2: the command data 4.
167  *
168  * @return LLVG_SUCCESS on a success, or the missing space in the array in bytes
169  *
170  * @see #VG_PATH_append_path_command0(jbyte*, uint32_t, jint)
171  */
172 uint32_t VG_PATH_append_path_command2(jbyte *path, jint array_length, jint cmd, jfloat x1, jfloat y1, jfloat x2,
173  jfloat y2);
174 
175 /*
176  * @brief Appends the command with 3 points parameter in the path's array.
177  *
178  * @param[in] path: the path's array
179  * @param[in] array_length: the length of the array
180  * @param[in] cmd: the command to add
181  * @param[in] x1: the command data 1.
182  * @param[in] y1: the command data 2.
183  * @param[in] x2: the command data 3.
184  * @param[in] y2: the command data 4.
185  * @param[in] x3: the command data 5.
186  * @param[in] y3: the command data 6.
187  *
188  * @return LLVG_SUCCESS on a success, or the missing space in the array in bytes
189  *
190  * @see #VG_PATH_append_path_command0(jbyte*, uint32_t, jint)
191  */
192 uint32_t VG_PATH_append_path_command3(jbyte *path, jint array_length, jint cmd, jfloat x1, jfloat y1, jfloat x2,
193  jfloat y2, jfloat x3, jfloat y3);
194 
195 /*
196  * @brief Gets the number of parameters for a specific command.
197  *
198  * @param[in] command: the command.
199  *
200  * @return the number of parameters for the given command.
201  */
202 uint32_t VG_PATH_get_command_parameter_number(jint command);
203 
204 #if defined(VG_FEATURE_PATH_DUAL_ARRAY) && (VG_FEATURE_PATH == VG_FEATURE_PATH_DUAL_ARRAY)
205 
206 /*
207  * @brief Returns a pointer to the beginning of a path's parameters
208  *
209  * @param[in] path the path
210  * @return a pointer to the first parameter
211  */
212 static inline VG_path_param_t * VG_PATH_get_path_param_begin(VG_PATH_HEADER_t *path) {
213  // cppcheck-suppress [misra-c2012-11.3,invalidPointerCast] cast is valid
214  return (VG_path_param_t *)(((uint8_t *)path) + VG_PATH_get_path_header_size());
215 }
216 
217 /*
218  * @brief Returns a pointer to the end of a path's parameters
219  *
220  * @param[in] path the path
221  * @return a pointer to the memory area immediately after the last parameter
222  */
223 static inline VG_path_param_t * VG_PATH_get_path_param_end(VG_PATH_HEADER_t *path) {
224  return (VG_PATH_get_path_param_begin(path)) + path->param_length;
225 }
226 
227 /*
228  * @brief Returns a pointer to the beginning of a path's commands
229  *
230  * @param[in] path the path
231  * @return a pointer to the first command
232  */
233 static inline VG_path_command_t * VG_PATH_get_path_command_begin(VG_PATH_HEADER_t *path) {
234  return ((uint8_t *)VG_PATH_get_path_param_begin(path)) + path->cmd_offset;
235 }
236 
237 /*
238  * @brief Returns a pointer to the end of a path's commands
239  *
240  * @param[in] path the path
241  * @return a pointer to the memory area immediately after the last command
242  */
243 static inline VG_path_command_t * VG_PATH_get_path_command_end(VG_PATH_HEADER_t *path) {
244  return (VG_PATH_get_path_command_begin(path)) + path->cmd_length;
245 }
246 
247 #endif // VG_FEATURE_PATH_DUAL_ARRAY
248 
249 // -----------------------------------------------------------------------------
250 // EOF
251 // -----------------------------------------------------------------------------
252 
253 #endif // VG_FEATURE_PATH
254 
255 #ifdef __cplusplus
256 }
257 #endif
258 
259 #endif // !defined VG_PATH_H
MicroEJ MicroVG library low level API: enable some features according to the hardware capacities.