Arm-2D  
2D Image Processing Library for Cortex-M Processors
 
Loading...
Searching...
No Matches
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_draw.h"
22 * Description: Public header file to contain the APIs for colour space
23 * conversions
24 *
25 * $Date: 13. Oct 2022
26 * $Revision: V.1.0.4
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# pragma clang diagnostic ignored "-Wpadded"
49#endif
50
51/*!
52 * \addtogroup Drawing 3 Drawing Operations
53 * @{
54 */
55
56/*============================ MACROS ========================================*/
57/*============================ MACROFIED FUNCTIONS ===========================*/
58
59#define arm_2dp_c8bit_draw_point arm_2dp_gray8_draw_point
60#define arm_2dp_rgb16_draw_point arm_2dp_rgb565_draw_point
61#define arm_2dp_rgb32_draw_point arm_2dp_cccn888_draw_point
62
63#define arm_2d_c8bit_draw_point(__TARGET_ADDR, /* target tile address */ \
64 __LOCATION, /* point coordinate */ \
65 __COLOUR) /* target colour */ \
66 arm_2dp_gray8_draw_point(NULL, \
67 (__TARGET_ADDR), \
68 (__LOCATION), \
69 (__COLOUR), \
70 (255))
71
72#define arm_2d_rgb16_draw_point(__TARGET_ADDR, /* target tile address */ \
73 __LOCATION, /* point coordinate */ \
74 __COLOUR) /* target colour */ \
75 arm_2dp_rgb565_draw_point(NULL, \
76 (__TARGET_ADDR), \
77 (__LOCATION), \
78 (__COLOUR), \
79 (255))
80
81#define arm_2d_rgb32_draw_point(__TARGET_ADDR, /* target tile address */ \
82 __LOCATION, /* point coordinate */ \
83 __COLOUR) /* target colour */ \
84 arm_2dp_cccn888_draw_point(NULL, \
85 (__TARGET_ADDR), \
86 (__LOCATION), \
87 (__COLOUR), \
88 (255))
89
90#define arm_2d_gray8_draw_point(__TARGET_ADDR, /* target tile address */ \
91 __LOCATION, /* point coordinate */ \
92 __COLOUR, /* target colour */ \
93 ...) \
94 arm_2dp_gray8_draw_point(NULL, \
95 (__TARGET_ADDR), \
96 (__LOCATION), \
97 (__COLOUR), \
98 (255,##__VA_ARGS__))
99
100#define arm_2d_rgb565_draw_point(__TARGET_ADDR, /* target tile address */ \
101 __LOCATION, /* point coordinate */ \
102 __COLOUR, /* target colour */ \
103 ...) \
104 arm_2dp_rgb565_draw_point(NULL, \
105 (__TARGET_ADDR), \
106 (__LOCATION), \
107 (__COLOUR), \
108 (255,##__VA_ARGS__))
109
110#define arm_2d_cccn888_draw_point(__TARGET_ADDR, /* target tile address */ \
111 __LOCATION, /* point coordinate */ \
112 __COLOUR, /* target colour */ \
113 ...) \
114 arm_2dp_cccn888_draw_point(NULL, \
115 (__TARGET_ADDR), \
116 (__LOCATION), \
117 (__COLOUR), \
118 (255,##__VA_ARGS__))
119
120
121#define arm_2d_c8bit_draw_pattern( __PATTERN_ADDR, /* pattern tile address */ \
122 __TARGET_ADDR, /* target tile address*/ \
123 __REGION_ADDR, /* target region address*/ \
124 __MODE, /* draw mode */ \
125 __FG_COLOUR, /* foreground colour */ \
126 __BG_COLOUR) /* background colour */ \
127 arm_2dp_c8bit_draw_pattern(NULL, \
128 (__PATTERN_ADDR), \
129 (__TARGET_ADDR), \
130 (__REGION_ADDR), \
131 (__MODE), \
132 (__FG_COLOUR), \
133 (__BG_COLOUR))
134
135#define arm_2d_rgb16_draw_pattern( __PATTERN_ADDR, /* pattern tile address */ \
136 __TARGET_ADDR, /* target tile address*/ \
137 __REGION_ADDR, /* target region address*/ \
138 __MODE, /* draw mode */ \
139 __FG_COLOUR, /* foreground colour */ \
140 __BG_COLOUR) /* background colour */ \
141 arm_2dp_rgb16_draw_pattern(NULL, \
142 (__PATTERN_ADDR), \
143 (__TARGET_ADDR), \
144 (__REGION_ADDR), \
145 (__MODE), \
146 (__FG_COLOUR), \
147 (__BG_COLOUR))
148
149#define arm_2d_rgb32_draw_pattern( __PATTERN_ADDR, /* pattern tile address */ \
150 __TARGET_ADDR, /* target tile address*/ \
151 __REGION_ADDR, /* target region address*/ \
152 __MODE, /* draw mode */ \
153 __FG_COLOUR, /* foreground colour */ \
154 __BG_COLOUR) /* background colour */ \
155 arm_2dp_rgb32_draw_pattern(NULL, \
156 (__PATTERN_ADDR), \
157 (__TARGET_ADDR), \
158 (__REGION_ADDR), \
159 (__MODE), \
160 (__FG_COLOUR), \
161 (__BG_COLOUR))
162
163#define arm_2d_c8bit_fill_colour( __TARGET_ADDR, /* target tile address*/ \
164 __REGION_ADDR, /* target region address*/ \
165 __COLOUR) /* colour */ \
166 arm_2dp_c8bit_fill_colour(NULL, \
167 (__TARGET_ADDR), \
168 (__REGION_ADDR), \
169 (__COLOUR))
170
171#define arm_2d_rgb16_fill_colour( __TARGET_ADDR, /* target tile address*/ \
172 __REGION_ADDR, /* target region address*/ \
173 __COLOUR) /* colour */ \
174 arm_2dp_rgb16_fill_colour(NULL, \
175 (__TARGET_ADDR), \
176 (__REGION_ADDR), \
177 (__COLOUR))
178
179#define arm_2d_rgb32_fill_colour( __TARGET_ADDR, /* target tile address*/ \
180 __REGION_ADDR, /* target region address*/ \
181 __COLOUR) /* colour */ \
182 arm_2dp_rgb32_fill_colour(NULL, \
183 (__TARGET_ADDR), \
184 (__REGION_ADDR), \
185 (__COLOUR))
186
187/*============================ TYPES =========================================*/
188
189/*!
190 * \brief the control block for colour-filling-operations
191 * \note arm_2d_op_fill_cl_t inherits from arm_2d_op_t explicitly
192 */
193typedef struct arm_2d_op_fill_cl_t {
194 inherit(arm_2d_op_core_t); //!< base
195 struct {
196 const arm_2d_tile_t *ptTile; //!< target tile
197 const arm_2d_region_t *ptRegion; //!< target region
198 } Target;
199 union {
200 uint8_t chColour; //!< 8bit colour
201 uint16_t hwColour; //!< 16bit colour
202 uint32_t wColour; //!< 32bit colour
203 };
204} arm_2d_op_fill_cl_t;
205
206/*!
207 * \brief the control block for drawing point
208 * \note arm_2d_op_drw_pt_t inherits from arm_2d_op_t explicitly
209 */
210typedef struct arm_2d_op_drw_pt_t {
211 inherit(arm_2d_op_core_t); //!< base
212 struct {
213 const arm_2d_tile_t *ptTile; //!< target tile
214 const arm_2d_region_t *ptRegion; //!< target region
215 } Target;
216 union {
217 uint8_t chColour; //!< 8bit colour
218 uint16_t hwColour; //!< 16bit colour
219 uint32_t wColour; //!< 32bit colour
220 };
221 uint8_t chOpaicty;
222 arm_2d_region_t tTargetRegion;
223} arm_2d_op_drw_pt_t;
224
225/*!
226 * \brief the control block for draw-bit-pattern operations
227 * \note arm_2d_op_drw_patn_t inherits from arm_2d_op_src_t explicitly
228 */
229typedef struct arm_2d_op_drw_patn_t {
230 inherit(arm_2d_op_core_t); //!< base
231
232 struct {
233 const arm_2d_tile_t *ptTile; //!< target tile
234 const arm_2d_region_t *ptRegion; //!< target region
235 } Target;
236 struct {
237 const arm_2d_tile_t *ptTile; //!< source tile
238 }Source;
239 uint32_t wMode; //!< mode of the operation
240 union {
241 uint8_t chColour; //!< 8bit colour
242 uint16_t hwColour; //!< 16bit colour
243 uint32_t wColour; //!< 32bit colour
244 }Foreground; //!< forground colour
245 union {
246 uint8_t chColour; //!< 8bit colour
247 uint16_t hwColour; //!< 16bit colour
248 uint32_t wColour; //!< 32bit colour
249 }Background; //!< background colour
250
251} arm_2d_op_drw_patn_t;
252
253
254/*!
255 * \brief modes for copying bit-patterns
256 */
257enum {
258 ARM_2D_DRW_PATN_MODE_COPY = 0, //!< copy bit pattern
259 //ARM_2D_DRW_PATN_MODE_FILL = _BV(0), //!< not support yet
260 //ARM_2D_DRW_PATN_MODE_Y_MIRROR = _BV(2), //!< not support yet
261 //ARM_2D_DRW_PATN_MODE_X_MIRROR = _BV(3), //!< not support yet
262 ARM_2D_DRW_PATN_MODE_WITH_BG_COLOR = _BV(4), //!< use user specified backgound colour
263 ARM_2D_DRW_PATN_MODE_NO_FG_COLOR = _BV(5), //!< no forground
264
265 /*! use complementary colour as foreground colour
266 *
267 * \note this option is only avaialble when ARM_2D_DRW_PATN_MODE_NO_FG_COLOR
268 * is used together.
269 */
270 ARM_2D_DRW_PATH_MODE_COMP_FG_COLOUR = _BV(6),
271};
272
273/*============================ GLOBAL VARIABLES ==============================*/
274/*============================ PROTOTYPES ====================================*/
275
276/*----------------------------------------------------------------------------*
277 * Draw a point with specified colour *
278 *----------------------------------------------------------------------------*/
279
280/*!
281 * \brief draw a point on a root tile with a given 8bit colour
282 * \param[in] ptTarget the target root tile
283 * \param[in] tLocation the target location
284 * \note the point must be inside the region of the target tile
285 * \param[in] chColour an 8bit colour
286 */
287ARM_NONNULL(1)
288__STATIC_INLINE void arm_2d_c8bit_draw_point_fast( const arm_2d_tile_t *ptTarget,
289 const arm_2d_location_t tLocation,
290 uint_fast8_t chColour)
291{
292 assert(NULL != ptTarget);
293 assert(ptTarget->bIsRoot); // must be root tile
294 assert(tLocation.iX < ptTarget->tRegion.tSize.iWidth);
295 assert(tLocation.iY < ptTarget->tRegion.tSize.iHeight);
296
297 uint8_t *pchPoint = ptTarget->pchBuffer
298 + tLocation.iY * ptTarget->tRegion.tSize.iWidth
299 + tLocation.iX;
300 *pchPoint = (uint8_t)chColour;
301}
302
303/*!
304 * \brief draw a point on a root tile with a given 16bit colour
305 * \param[in] ptTarget the target root tile
306 * \param[in] tLocation the target location
307 * \note the point must be inside the region of the target tile
308 * \param[in] hwColour an 16bit colour
309 */
310ARM_NONNULL(1)
311__STATIC_INLINE void arm_2d_rgb16_draw_point_fast(
312 const arm_2d_tile_t *ptTarget,
313 const arm_2d_location_t tLocation,
314 uint_fast16_t hwColour)
315{
316 assert(NULL != ptTarget);
317 assert(ptTarget->bIsRoot); // must be root tile
318 assert(tLocation.iX < ptTarget->tRegion.tSize.iWidth);
319 assert(tLocation.iY < ptTarget->tRegion.tSize.iHeight);
320
321 uint16_t *phwPoint = ptTarget->phwBuffer
322 + tLocation.iY * ptTarget->tRegion.tSize.iWidth
323 + tLocation.iX;
324 *phwPoint = (uint16_t)hwColour;
325}
326
327/*!
328 * \brief draw a point on a root tile with a given 32bit colour
329 * \param[in] ptTarget the target root tile
330 * \param[in] tLocation the target location
331 * \note the point must be inside the region of the target tile
332 * \param[in] wColour an 32bit colour
333 */
334ARM_NONNULL(1)
335__STATIC_INLINE void arm_2d_rgb32_draw_point_fast(
336 const arm_2d_tile_t *ptTarget,
337 const arm_2d_location_t tLocation,
338 uint32_t wColour)
339{
340 assert(NULL != ptTarget);
341 assert(ptTarget->bIsRoot); // must be root tile
342 assert(tLocation.iX < ptTarget->tRegion.tSize.iWidth);
343 assert(tLocation.iY < ptTarget->tRegion.tSize.iHeight);
344
345 uint32_t *pwPoint = ptTarget->pwBuffer
346 + tLocation.iY * ptTarget->tRegion.tSize.iWidth
347 + tLocation.iX;
348 *pwPoint = wColour;
349}
350
351/*!
352 * \brief draw a point with a given gray8 colour
353 * \param[in] ptOP the control block, NULL means using the default control block
354 * \param[in] ptTarget the target root tile
355 * \param[in] tLocation the target location
356 * \param[in] chColour an 8bit colour
357 * \param[in] chOpacity the point opacity
358 * \return arm_fsm_rt_t the operation result
359 *
360 * \note As those draw point APIs involve the region calculation
361 * which is only useful when partial framebuffer is used, it is slow.
362 * For gettting better performance, if the target tile is root and the
363 * target location is inside the target region, please use the
364 * functions with "_fast" posfix.
365 *
366 */
367extern
368ARM_NONNULL(2)
369arm_fsm_rt_t arm_2dp_gray8_draw_point( arm_2d_op_drw_pt_t *ptOP,
370 const arm_2d_tile_t *ptTarget,
371 const arm_2d_location_t tLocation,
372 uint_fast8_t chColour,
373 uint8_t chOpacity);
374
375/*!
376 * \brief draw a point with a given rgb565 colour
377 * \param[in] ptOP the control block, NULL means using the default control block
378 * \param[in] ptTarget the target root tile
379 * \param[in] tLocation the target location
380 * \param[in] hwColour an 16bit colour
381 * \param[in] chOpacity the point opacity
382 * \return arm_fsm_rt_t the operation result
383 *
384 * \note As those draw point APIs involve the region calculation
385 * which is only useful when partial framebuffer is used, it is slow.
386 * For gettting better performance, if the target tile is root and the
387 * target location is inside the target region, please use the
388 * functions with "_fast" posfix.
389 *
390 */
391extern
392ARM_NONNULL(2)
393arm_fsm_rt_t arm_2dp_rgb565_draw_point( arm_2d_op_drw_pt_t *ptOP,
394 const arm_2d_tile_t *ptTarget,
395 const arm_2d_location_t tLocation,
396 uint_fast16_t hwColour,
397 uint8_t chOpacity);
398
399/*!
400 * \brief draw a point with a given cccn888 colour
401 * \param[in] ptOP the control block, NULL means using the default control block
402 * \param[in] ptTarget the target root tile
403 * \param[in] tLocation the target location
404 * \param[in] wColour an 32bit colour
405 * \param[in] chOpacity the point opacity
406 * \return arm_fsm_rt_t the operation result
407 *
408 * \note As those draw point APIs involve the region calculation
409 * which is only useful when partial framebuffer is used, it is slow.
410 * For gettting better performance, if the target tile is root and the
411 * target location is inside the target region, please use the
412 * functions with "_fast" posfix.
413 *
414 */
415extern
416ARM_NONNULL(2)
417arm_fsm_rt_t arm_2dp_cccn888_draw_point( arm_2d_op_drw_pt_t *ptOP,
418 const arm_2d_tile_t *ptTarget,
419 const arm_2d_location_t tLocation,
420 uint32_t wColour,
421 uint8_t chOpacity);
422
423
424#if 0 // todo: draw point with alpha
425extern
426ARM_NONNULL(1)
427arm_fsm_rt_t arm_2d_rgba8888_draw_point(const arm_2d_tile_t *ptTarget,
428 const arm_2d_location_t tLocation,
429 arm_2d_color_bgra8888_t tColour);
430#endif
431
432
433/*----------------------------------------------------------------------------*
434 * Draw a bit patterns *
435 *----------------------------------------------------------------------------*/
436
437/*!
438 * \brief copy a bit-pattern with given 8bit colours
439 * \param[in] ptOP the control block, NULL means using the default control block
440 * \param[in] ptPattern the source bit pattern
441 * \param[in] ptTarget the target tile
442 * \param[in] ptRegion the target region
443 * \param[in] wMode the copy mode
444 * \param[in] chForeColour the foreground colour
445 * \param[in] chBackColour the background colour
446 * \return arm_fsm_rt_t the operation result
447 */
448extern
449ARM_NONNULL(2,3)
450arm_fsm_rt_t arm_2dp_c8bit_draw_pattern( arm_2d_op_drw_patn_t *ptOP,
451 const arm_2d_tile_t *ptPattern,
452 const arm_2d_tile_t *ptTarget,
453 const arm_2d_region_t *ptRegion,
454 uint32_t wMode,
455 uint8_t chForeColour,
456 uint8_t chBackColour);
457
458/*!
459 * \brief copy a bit-pattern with given 16bit colours
460 * \param[in] ptOP the control block, NULL means using the default control block
461 * \param[in] ptPattern the source bit pattern
462 * \param[in] ptTarget the target tile
463 * \param[in] ptRegion the target region
464 * \param[in] wMode the copy mode
465 * \param[in] hwForeColour the foreground colour
466 * \param[in] hwBackColour the background colour
467 * \return arm_fsm_rt_t the operation result
468 */
469extern
470ARM_NONNULL(2,3)
471arm_fsm_rt_t arm_2dp_rgb16_draw_pattern( arm_2d_op_drw_patn_t *ptOP,
472 const arm_2d_tile_t *ptPattern,
473 const arm_2d_tile_t *ptTarget,
474 const arm_2d_region_t *ptRegion,
475 uint32_t wMode,
476 uint16_t hwForeColour,
477 uint16_t hwBackColour);
478
479/*!
480 * \brief copy a bit-pattern with given 32bit colours
481 * \param[in] ptOP the control block, NULL means using the default control block
482 * \param[in] ptPattern the source bit pattern
483 * \param[in] ptTarget the target tile
484 * \param[in] ptRegion the target region
485 * \param[in] wMode the copy mode
486 * \param[in] wForeColour the foreground colour
487 * \param[in] wBackColour the background colour
488 * \return arm_fsm_rt_t the operation result
489 */
490extern
491ARM_NONNULL(2,3)
492arm_fsm_rt_t arm_2dp_rgb32_draw_pattern( arm_2d_op_drw_patn_t *ptOP,
493 const arm_2d_tile_t *ptPattern,
494 const arm_2d_tile_t *ptTarget,
495 const arm_2d_region_t *ptRegion,
496 uint32_t wMode,
497 uint32_t wForeColour,
498 uint32_t wBackColour);
499
500/*----------------------------------------------------------------------------*
501 * Fill tile with a specified colour *
502 *----------------------------------------------------------------------------*/
503
504/*!
505 * \brief fill the target region with a given 8bit colour
506 * \param[in] ptOP the control block, NULL means using the default control block
507 * \param[in] ptTarget the target tile
508 * \param[in] ptRegion the target region
509 * \param[in] chColour a 8bit colour
510 * \return arm_fsm_rt_t the operation result
511 */
512extern
513ARM_NONNULL(2)
514arm_fsm_rt_t arm_2dp_c8bit_fill_colour( arm_2d_op_fill_cl_t *ptOP,
515 const arm_2d_tile_t *ptTarget,
516 const arm_2d_region_t *ptRegion,
517 uint_fast8_t chColour);
518
519/*!
520 * \brief fill the target region with a given 16bit colour
521 * \param[in] ptOP the control block, NULL means using the default control block
522 * \param[in] ptTarget the target tile
523 * \param[in] ptRegion the target region
524 * \param[in] hwColour a 16bit colour
525 * \return arm_fsm_rt_t the operation result
526 */
527extern
528ARM_NONNULL(2)
529arm_fsm_rt_t arm_2dp_rgb16_fill_colour( arm_2d_op_fill_cl_t *ptOP,
530 const arm_2d_tile_t *ptTarget,
531 const arm_2d_region_t *ptRegion,
532 uint_fast16_t hwColour);
533
534/*!
535 * \brief fill the target region with a given 32bit colour
536 * \param[in] ptOP the control block, NULL means using the default control block
537 * \param[in] ptTarget the target tile
538 * \param[in] ptRegion the target region
539 * \param[in] wColour a 32bit colour
540 * \return arm_fsm_rt_t the operations result
541 */
542extern
543ARM_NONNULL(2)
544arm_fsm_rt_t arm_2dp_rgb32_fill_colour( arm_2d_op_fill_cl_t *ptOP,
545 const arm_2d_tile_t *ptTarget,
546 const arm_2d_region_t *ptRegion,
547 uint32_t wColour);
548
549
550/*! @} */
551
552#if defined(__clang__)
553# pragma clang diagnostic pop
554#endif
555
556#ifdef __cplusplus
557}
558#endif
559
560#endif