Arm-2D  
2D Image Processing Library for Cortex-M Processors
arm_2d_draw.h
1/*
2 * Copyright (C) 2022 Arm Limited or its affiliates. All rights reserved.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 *
6 * Licensed under the Apache License, Version 2.0 (the License); you may
7 * not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19/* ----------------------------------------------------------------------
20 * Project: Arm-2D Library
21 * Title: #include "arm_2d.h"
22 * Description: Public header file to contain the APIs for colour space
23 * conversions
24 *
25 * $Date: 17. June 2022
26 * $Revision: V.1.0.2
27 *
28 * Target Processor: Cortex-M cores
29 * -------------------------------------------------------------------- */
30
31#ifndef __ARM_2D_DRAW_H__
32#define __ARM_2D_DRAW_H__
33
34/*============================ INCLUDES ======================================*/
35
36#include "arm_2d_types.h"
37
38#ifdef __cplusplus
39extern "C" {
40#endif
41
42#if defined(__clang__)
43# pragma clang diagnostic push
44# pragma clang diagnostic ignored "-Wunknown-warning-option"
45# pragma clang diagnostic ignored "-Wreserved-identifier"
46# pragma clang diagnostic ignored "-Wdeclaration-after-statement"
47# pragma clang diagnostic ignored "-Wsign-conversion"
48#endif
49
50/*!
51 * \addtogroup Drawing 3 Drawing Operations
52 * @{
53 */
54
55/*============================ MACROS ========================================*/
56/*============================ MACROFIED FUNCTIONS ===========================*/
57
58#define arm_2d_c8bit_draw_point(__TARGET_ADDR, /* target tile address */ \
59 __LOCATION, /* point coordinate */ \
60 __COLOUR) /* target colour */ \
61 arm_2dp_c8bit_draw_point(NULL, \
62 (__TARGET_ADDR), \
63 (__LOCATION), \
64 (__COLOUR))
65
66#define arm_2d_rgb16_draw_point(__TARGET_ADDR, /* target tile address */ \
67 __LOCATION, /* point coordinate */ \
68 __COLOUR) /* target colour */ \
69 arm_2dp_rgb16_draw_point(NULL, \
70 (__TARGET_ADDR), \
71 (__LOCATION), \
72 (__COLOUR))
73
74#define arm_2d_rgb32_draw_point(__TARGET_ADDR, /* target tile address */ \
75 __LOCATION, /* point coordinate */ \
76 __COLOUR) /* target colour */ \
77 arm_2dp_rgb32_draw_point(NULL, \
78 (__TARGET_ADDR), \
79 (__LOCATION), \
80 (__COLOUR))
81
82
83#define arm_2d_c8bit_draw_pattern( __PATTERN_ADDR, /* pattern tile address */ \
84 __TARGET_ADDR, /* target tile address*/ \
85 __REGION_ADDR, /* target region address*/ \
86 __MODE, /* draw mode */ \
87 __FG_COLOUR, /* foreground colour */ \
88 __BG_COLOUR) /* background colour */ \
89 arm_2dp_c8bit_draw_pattern(NULL, \
90 (__PATTERN_ADDR), \
91 (__TARGET_ADDR), \
92 (__REGION_ADDR), \
93 (__MODE), \
94 (__FG_COLOUR), \
95 (__BG_COLOUR))
96
97#define arm_2d_rgb16_draw_pattern( __PATTERN_ADDR, /* pattern tile address */ \
98 __TARGET_ADDR, /* target tile address*/ \
99 __REGION_ADDR, /* target region address*/ \
100 __MODE, /* draw mode */ \
101 __FG_COLOUR, /* foreground colour */ \
102 __BG_COLOUR) /* background colour */ \
103 arm_2dp_rgb16_draw_pattern(NULL, \
104 (__PATTERN_ADDR), \
105 (__TARGET_ADDR), \
106 (__REGION_ADDR), \
107 (__MODE), \
108 (__FG_COLOUR), \
109 (__BG_COLOUR))
110
111#define arm_2d_rgb32_draw_pattern( __PATTERN_ADDR, /* pattern tile address */ \
112 __TARGET_ADDR, /* target tile address*/ \
113 __REGION_ADDR, /* target region address*/ \
114 __MODE, /* draw mode */ \
115 __FG_COLOUR, /* foreground colour */ \
116 __BG_COLOUR) /* background colour */ \
117 arm_2dp_rgb32_draw_pattern(NULL, \
118 (__PATTERN_ADDR), \
119 (__TARGET_ADDR), \
120 (__REGION_ADDR), \
121 (__MODE), \
122 (__FG_COLOUR), \
123 (__BG_COLOUR))
124
125#define arm_2d_c8bit_fill_colour( __TARGET_ADDR, /* target tile address*/ \
126 __REGION_ADDR, /* target region address*/ \
127 __COLOUR) /* colour */ \
128 arm_2dp_c8bit_fill_colour(NULL, \
129 (__TARGET_ADDR), \
130 (__REGION_ADDR), \
131 (__COLOUR))
132
133#define arm_2d_rgb16_fill_colour( __TARGET_ADDR, /* target tile address*/ \
134 __REGION_ADDR, /* target region address*/ \
135 __COLOUR) /* colour */ \
136 arm_2dp_rgb16_fill_colour(NULL, \
137 (__TARGET_ADDR), \
138 (__REGION_ADDR), \
139 (__COLOUR))
140
141#define arm_2d_rgb32_fill_colour( __TARGET_ADDR, /* target tile address*/ \
142 __REGION_ADDR, /* target region address*/ \
143 __COLOUR) /* colour */ \
144 arm_2dp_rgb32_fill_colour(NULL, \
145 (__TARGET_ADDR), \
146 (__REGION_ADDR), \
147 (__COLOUR))
148
149/*============================ TYPES =========================================*/
150
151/*!
152 * \brief the control block for colour-filling-operations
153 * \note arm_2d_op_fill_cl_t inherits from arm_2d_op_t explicitly
154 */
155typedef struct arm_2d_op_fill_cl_t {
156 inherit(arm_2d_op_core_t); //!< base
157 struct {
158 const arm_2d_tile_t *ptTile; //!< target tile
159 const arm_2d_region_t *ptRegion; //!< target region
160 } Target;
161 union {
162 uint8_t chColour; //!< 8bit colour
163 uint16_t hwColour; //!< 16bit colour
164 uint32_t wColour; //!< 32bit colour
165 };
167
168/*! \note arm_2d_op_fill_cl_t inherits from arm_2d_op_t explicitly
169 */
171
172/*!
173 * \brief the control block for draw-bit-pattern operations
174 * \note arm_2d_op_drw_patn_t inherits from arm_2d_op_src_t explicitly
175 */
176typedef struct arm_2d_op_drw_patn_t {
177 inherit(arm_2d_op_core_t); //!< base
178
179 struct {
180 const arm_2d_tile_t *ptTile; //!< target tile
181 const arm_2d_region_t *ptRegion; //!< target region
182 } Target;
183 struct {
184 const arm_2d_tile_t *ptTile; //!< source tile
185 }Source;
186 uint32_t wMode; //!< mode of the operation
187 union {
188 uint8_t chColour; //!< 8bit colour
189 uint16_t hwColour; //!< 16bit colour
190 uint32_t wColour; //!< 32bit colour
191 }Foreground; //!< forground colour
192 union {
193 uint8_t chColour; //!< 8bit colour
194 uint16_t hwColour; //!< 16bit colour
195 uint32_t wColour; //!< 32bit colour
196 }Background; //!< background colour
197
199
200
201/*!
202 * \brief modes for copying bit-patterns
203 */
204enum {
205 ARM_2D_DRW_PATN_MODE_COPY = 0, //!< copy bit pattern
206 //ARM_2D_DRW_PATN_MODE_FILL = _BV(0), //!< not support yet
207 //ARM_2D_DRW_PATN_MODE_Y_MIRROR = _BV(2), //!< not support yet
208 //ARM_2D_DRW_PATN_MODE_X_MIRROR = _BV(3), //!< not support yet
209 ARM_2D_DRW_PATN_MODE_WITH_BG_COLOR = _BV(4), //!< use user specified backgound colour
210 ARM_2D_DRW_PATN_MODE_NO_FG_COLOR = _BV(5), //!< no forground
211
212 /*! use complementary colour as foreground colour
213 *
214 * \note this option is only avaialble when ARM_2D_DRW_PATN_MODE_NO_FG_COLOR
215 * is used together.
216 */
218};
219
220/*============================ GLOBAL VARIABLES ==============================*/
221/*============================ PROTOTYPES ====================================*/
222
223/*----------------------------------------------------------------------------*
224 * Draw a point with specified colour *
225 *----------------------------------------------------------------------------*/
226
227/*!
228 * \brief draw a point on a root tile with a given 8bit colour
229 * \param[in] ptTarget the target root tile
230 * \param[in] tLocation the target location
231 * \note the point must be inside the region of the target tile
232 * \param[in] chColour an 8bit colour
233 */
234ARM_NONNULL(1)
235__STATIC_INLINE void arm_2d_c8bit_draw_point_fast( const arm_2d_tile_t *ptTarget,
236 const arm_2d_location_t tLocation,
237 uint_fast8_t chColour)
238{
239 assert(NULL != ptTarget);
240 assert(ptTarget->bIsRoot); // must be root tile
241 assert(tLocation.iX < ptTarget->tRegion.tSize.iWidth);
242 assert(tLocation.iY < ptTarget->tRegion.tSize.iHeight);
243
244 uint8_t *pchPoint = ptTarget->pchBuffer
245 + tLocation.iY * ptTarget->tRegion.tSize.iWidth
246 + tLocation.iX;
247 *pchPoint = (uint8_t)chColour;
248}
249
250/*!
251 * \brief draw a point on a root tile with a given 16bit colour
252 * \param[in] ptTarget the target root tile
253 * \param[in] tLocation the target location
254 * \note the point must be inside the region of the target tile
255 * \param[in] hwColour an 16bit colour
256 */
257ARM_NONNULL(1)
258__STATIC_INLINE void arm_2d_rgb16_draw_point_fast(
259 const arm_2d_tile_t *ptTarget,
260 const arm_2d_location_t tLocation,
261 uint_fast16_t hwColour)
262{
263 assert(NULL != ptTarget);
264 assert(ptTarget->bIsRoot); // must be root tile
265 assert(tLocation.iX < ptTarget->tRegion.tSize.iWidth);
266 assert(tLocation.iY < ptTarget->tRegion.tSize.iHeight);
267
268 uint16_t *phwPoint = ptTarget->phwBuffer
269 + tLocation.iY * ptTarget->tRegion.tSize.iWidth
270 + tLocation.iX;
271 *phwPoint = (uint16_t)hwColour;
272}
273
274/*!
275 * \brief draw a point on a root tile with a given 32bit colour
276 * \param[in] ptTarget the target root tile
277 * \param[in] tLocation the target location
278 * \note the point must be inside the region of the target tile
279 * \param[in] wColour an 32bit colour
280 */
281ARM_NONNULL(1)
282__STATIC_INLINE void arm_2d_rgb32_draw_point_fast(
283 const arm_2d_tile_t *ptTarget,
284 const arm_2d_location_t tLocation,
285 uint32_t wColour)
286{
287 assert(NULL != ptTarget);
288 assert(ptTarget->bIsRoot); // must be root tile
289 assert(tLocation.iX < ptTarget->tRegion.tSize.iWidth);
290 assert(tLocation.iY < ptTarget->tRegion.tSize.iHeight);
291
292 uint32_t *pwPoint = ptTarget->pwBuffer
293 + tLocation.iY * ptTarget->tRegion.tSize.iWidth
294 + tLocation.iX;
295 *pwPoint = wColour;
296}
297
298/*!
299 * \brief draw a point with a given 8bit colour
300 * \param[in] ptOP the control block, NULL means using the default control block
301 * \param[in] ptTarget the target root tile
302 * \param[in] tLocation the target location
303 * \param[in] chColour an 8bit colour
304 * \return arm_fsm_rt_t the operation result
305 *
306 * \note As those draw point APIs involve the region calculation
307 * which is only useful when partial framebuffer is used, it is slow.
308 * For gettting better performance, if the target tile is root and the
309 * target location is inside the target region, please use the
310 * functions with "_fast" posfix.
311 *
312 */
313extern
314ARM_NONNULL(2)
316 const arm_2d_tile_t *ptTarget,
317 const arm_2d_location_t tLocation,
318 uint_fast8_t chColour);
319
320/*!
321 * \brief draw a point with a given 16bit colour
322 * \param[in] ptOP the control block, NULL means using the default control block
323 * \param[in] ptTarget the target root tile
324 * \param[in] tLocation the target location
325 * \param[in] hwColour an 16bit colour
326 * \return arm_fsm_rt_t the operation result
327 *
328 * \note As those draw point APIs involve the region calculation
329 * which is only useful when partial framebuffer is used, it is slow.
330 * For gettting better performance, if the target tile is root and the
331 * target location is inside the target region, please use the
332 * functions with "_fast" posfix.
333 *
334 */
335extern
336ARM_NONNULL(2)
338 const arm_2d_tile_t *ptTarget,
339 const arm_2d_location_t tLocation,
340 uint_fast16_t hwColour);
341
342/*!
343 * \brief draw a point with a given 32bit colour
344 * \param[in] ptOP the control block, NULL means using the default control block
345 * \param[in] ptTarget the target root tile
346 * \param[in] tLocation the target location
347 * \param[in] wColour an 32bit colour
348 * \return arm_fsm_rt_t the operation result
349 *
350 * \note As those draw point APIs involve the region calculation
351 * which is only useful when partial framebuffer is used, it is slow.
352 * For gettting better performance, if the target tile is root and the
353 * target location is inside the target region, please use the
354 * functions with "_fast" posfix.
355 *
356 */
357extern
358ARM_NONNULL(2)
360 const arm_2d_tile_t *ptTarget,
361 const arm_2d_location_t tLocation,
362 uint32_t wColour);
363
364
365#if 0 // todo: draw point with alpha
366extern
367ARM_NONNULL(1)
368arm_fsm_rt_t arm_2d_rgba8888_draw_point(const arm_2d_tile_t *ptTarget,
369 const arm_2d_location_t tLocation,
371#endif
372
373
374/*----------------------------------------------------------------------------*
375 * Draw a bit patterns *
376 *----------------------------------------------------------------------------*/
377
378/*!
379 * \brief copy a bit-pattern with given 8bit colours
380 * \param[in] ptOP the control block, NULL means using the default control block
381 * \param[in] ptPattern the source bit pattern
382 * \param[in] ptTarget the target tile
383 * \param[in] ptRegion the target region
384 * \param[in] wMode the copy mode
385 * \param[in] chForeColour the foreground colour
386 * \param[in] chBackColour the background colour
387 * \return arm_fsm_rt_t the operation result
388 */
389extern
390ARM_NONNULL(2,3)
392 const arm_2d_tile_t *ptPattern,
393 const arm_2d_tile_t *ptTarget,
394 const arm_2d_region_t *ptRegion,
395 uint32_t wMode,
396 uint8_t chForeColour,
397 uint8_t chBackColour);
398
399/*!
400 * \brief copy a bit-pattern with given 16bit colours
401 * \param[in] ptOP the control block, NULL means using the default control block
402 * \param[in] ptPattern the source bit pattern
403 * \param[in] ptTarget the target tile
404 * \param[in] ptRegion the target region
405 * \param[in] wMode the copy mode
406 * \param[in] hwForeColour the foreground colour
407 * \param[in] hwBackColour the background colour
408 * \return arm_fsm_rt_t the operation result
409 */
410extern
411ARM_NONNULL(2,3)
413 const arm_2d_tile_t *ptPattern,
414 const arm_2d_tile_t *ptTarget,
415 const arm_2d_region_t *ptRegion,
416 uint32_t wMode,
417 uint16_t hwForeColour,
418 uint16_t hwBackColour);
419
420/*!
421 * \brief copy a bit-pattern with given 32bit colours
422 * \param[in] ptOP the control block, NULL means using the default control block
423 * \param[in] ptPattern the source bit pattern
424 * \param[in] ptTarget the target tile
425 * \param[in] ptRegion the target region
426 * \param[in] wMode the copy mode
427 * \param[in] wForeColour the foreground colour
428 * \param[in] wBackColour the background colour
429 * \return arm_fsm_rt_t the operation result
430 */
431extern
432ARM_NONNULL(2,3)
434 const arm_2d_tile_t *ptPattern,
435 const arm_2d_tile_t *ptTarget,
436 const arm_2d_region_t *ptRegion,
437 uint32_t wMode,
438 uint32_t wForeColour,
439 uint32_t wBackColour);
440
441/*----------------------------------------------------------------------------*
442 * Fill tile with a specified colour *
443 *----------------------------------------------------------------------------*/
444
445/*!
446 * \brief fill the target region with a given 8bit colour
447 * \param[in] ptOP the control block, NULL means using the default control block
448 * \param[in] ptTarget the target tile
449 * \param[in] ptRegion the target region
450 * \param[in] chColour a 8bit colour
451 * \return arm_fsm_rt_t the operation result
452 */
453extern
454ARM_NONNULL(2)
456 const arm_2d_tile_t *ptTarget,
457 const arm_2d_region_t *ptRegion,
458 uint_fast8_t chColour);
459
460/*!
461 * \brief fill the target region with a given 16bit colour
462 * \param[in] ptOP the control block, NULL means using the default control block
463 * \param[in] ptTarget the target tile
464 * \param[in] ptRegion the target region
465 * \param[in] hwColour a 16bit colour
466 * \return arm_fsm_rt_t the operation result
467 */
468extern
469ARM_NONNULL(2)
471 const arm_2d_tile_t *ptTarget,
472 const arm_2d_region_t *ptRegion,
473 uint_fast16_t hwColour);
474
475/*!
476 * \brief fill the target region with a given 32bit colour
477 * \param[in] ptOP the control block, NULL means using the default control block
478 * \param[in] ptTarget the target tile
479 * \param[in] ptRegion the target region
480 * \param[in] wColour a 32bit colour
481 * \return arm_fsm_rt_t the operations result
482 */
483extern
484ARM_NONNULL(2)
486 const arm_2d_tile_t *ptTarget,
487 const arm_2d_region_t *ptRegion,
488 uint32_t wColour);
489
490
491/*! @} */
492
493#if defined(__clang__)
494# pragma clang diagnostic pop
495#endif
496
497#ifdef __cplusplus
498}
499#endif
500
501#endif