MPLAB® Harmony Graphics Suite
legato_pixelbuffer.h
Go to the documentation of this file.
1 /*******************************************************************************
2 * Copyright (C) 2020 Microchip Technology Inc. and its subsidiaries.
3 *
4 * Subject to your compliance with these terms, you may use Microchip software
5 * and any derivatives exclusively with Microchip products. It is your
6 * responsibility to comply with third party license terms applicable to your
7 * use of third party software (including open source software) that may
8 * accompany Microchip software.
9 *
10 * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, WHETHER
11 * EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, INCLUDING ANY IMPLIED
12 * WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A
13 * PARTICULAR PURPOSE.
14 *
15 * IN NO EVENT WILL MICROCHIP BE LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE,
16 * INCIDENTAL OR CONSEQUENTIAL LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND
17 * WHATSOEVER RELATED TO THE SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS
18 * BEEN ADVISED OF THE POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE
19 * FULLEST EXTENT ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN
20 * ANY WAY RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY,
21 * THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.
22 *******************************************************************************/
23 
24 /*******************************************************************************
25  Module for Microchip Graphics Library - Legato User Interface Library
26 
27  Company:
28  Microchip Technology Inc.
29 
30  File Name:
31  legato_pixelbuffer.h
32 
33  Summary:
34  Defines a general purpose pixel buffer construct.
35 
36  Description:
37  Pixel buffer generation and management functions.
38 *******************************************************************************/
39 
46 #ifndef LE_PIXELBUFFER_H
47 #define LE_PIXELBUFFER_H
48 
49 #include "gfx/legato/common/legato_color.h"
50 
51 // DOM-IGNORE-BEGIN
52 #ifdef __cplusplus
53  extern "C" {
54 #endif
55 // DOM-IGNORE-END
56 
57 // *****************************************************************************
58 // *****************************************************************************
59 // Section: Data Types and Constants
60 // *****************************************************************************
61 // *****************************************************************************
65 enum BufferFlags
66 {
67  BF_NONE = 0,
68  BF_LOCKED = 1 << 0,
69 };
70 
71 // *****************************************************************************
72 /* Structure:
73  lePixelBuffer
74 
75  Summary:
76  A pixel buffer is a wrapper around a basic data pointer. A pixel buffer
77  has a color mode, a pixel count, a rectangular dimension, a pixel count,
78  and a lenght in bytes.
79 
80  Description:
81  mode - the color mode of the pixel buffer
82  size - the width and height dimension of the pixel buffer
83  pixel_count - the total number of pixels in the buffer
84  buffer_length - the total size of the buffer in bytes
85  pixels - the pointer to the pixel data for the buffer
86 
87  Remarks:
88  None.
89 */
90 typedef struct lePixelBuffer
91 {
92  leColorMode mode;
93 
94  leSize size;
95  uint32_t pixel_count;
96 
97  uint32_t buffer_length;
98  leBuffer pixels;
99 
100  uint32_t flags;
101 } lePixelBuffer;
102 
103 // *****************************************************************************
104 // *****************************************************************************
105 // Section: Routines
106 // *****************************************************************************
107 // *****************************************************************************
108 
109 // *****************************************************************************
110 /* Function:
111  leResult lePixelBufferCreate(const int32_t width,
112  const int32_t height,
113  const leColorMode mode,
114  const void* const address,
115  lePixelBuffer* buffer)
116 
117  Summary:
118  Initializes a pixel buffer struct. Does not actually allocate any memory.
119 
120  Parameters:
121  const int32_t - the width of the buffer
122  const int32_t - the height of the buffer
123  const leColorMode - the color mode of the buffer
124  const void* - the data addres of the buffer (may be NULL)
125  lePixelBuffer* - pointer of the pixel buffer buffer to initialize
126 
127  Returns:
128  leResult
129 
130  Remarks:
131 
132 */
143 LIB_EXPORT leResult lePixelBufferCreate(const int32_t width,
144  const int32_t height,
145  const leColorMode mode,
146  const void* const address,
147  lePixelBuffer* buffer);
148 
149 // *****************************************************************************
150 /* Function:
151  leBuffer lePixelBufferOffsetGet(const lePixelBuffer* const buffer,
152  const lePoint* const pnt)
153 
154  Summary:
155  Gets the offset address of the pixel that resides at the provided
156  point in the given buffer.
157 
158  Parameters:
159  const lePixelBuffer* - the source buffer
160  const lePoint* - the point for which the offset should be calculated
161 
162  Returns:
163  leBuffer - the pointer to the offset point in the source buffer
164 */
176 LIB_EXPORT leBuffer lePixelBufferOffsetGet(const lePixelBuffer* const buffer,
177  uint32_t x,
178  uint32_t y);
179 
180 // *****************************************************************************
181 /* Function:
182  leBuffer lePixelBufferOffsetGet_Unsafe(const lePixelBuffer* const buffer,
183  const lePoint* const pnt)
184 
185  Summary:
186  Gets the offset address of the pixel that resides at the provided
187  point in the given buffer. Similar to lePixelBufferOffsetGet but performs
188  no bounds checking.
189 
190  Parameters:
191  const lePixelBuffer* - the source buffer
192  const lePoint* - the point for which the offset should be calculated
193 
194  Returns:
195  leBuffer - the pointer to the offset point in the source buffer
196 */
209 LIB_EXPORT leBuffer lePixelBufferOffsetGet_Unsafe(const lePixelBuffer* const buffer,
210  uint32_t x,
211  uint32_t y);
212 
213 // *****************************************************************************
214 /* Function:
215  leColor lePixelBufferGet(const lePixelBuffer* const buffer,
216  const lePoint* const pnt)
217 
218  Summary:
219  Gets the value of the pixel that resides at the provided point in
220  the given buffer.
221 
222  Parameters:
223  const lePixelBuffer* - the source buffer
224  const lePoint* - the point for which the offset should be calculated
225 
226  Returns:
227  leColor - the value of the pixel at the point in the source buffer
228 */
240 LIB_EXPORT leColor lePixelBufferGet(const lePixelBuffer* const buffer,
241  uint32_t x,
242  uint32_t y);
243 
244 // *****************************************************************************
245 /* Function:
246  leColor lePixelBufferGet_Unsafe(const lePixelBuffer* const buffer,
247  const lePoint* const pnt)
248 
249  Summary:
250  Gets the value of the pixel that resides at the provided point in
251  the given buffer. Like lePixelBufferGet but performs no bounds checking.
252 
253  Parameters:
254  const lePixelBuffer* - the source buffer
255  const lePoint* - the point for which the offset should be calculated
256 
257  Returns:
258  leColor - the value of the pixel at the point in the source buffer
259 */
271 LIB_EXPORT leColor lePixelBufferGet_Unsafe(const lePixelBuffer* const buffer,
272  uint32_t x,
273  uint32_t y);
274 
287 LIB_EXPORT leColor lePixelBufferGetIndex_Unsafe(const lePixelBuffer* const buffer,
288  const uint32_t idx);
289 
290 
301 leColor lePixelBufferGetIndex_Unsafe(const lePixelBuffer* const buffer,
302  const uint32_t idx);
303 
304 // *****************************************************************************
305 /* Function:
306  leResult lePixelBufferClipRect(const lePixelBuffer* const buffer,
307  const leRect* const rect,
308  leRect* result)
309 
310  Summary:
311  Clips a rectangle against a pixel buffer. The result is guaranteed to fit
312  inside the buffer's area.
313 
314  Parameters:
315  const lePixelBuffer* const buffer - the source buffer
316  const leRect* const - the rectangle to analyze
317  leRect* result - the clipped rectangle
318 
319  Returns:
320  leResult
321 */
333 LIB_EXPORT leResult lePixelBufferClipRect(const lePixelBuffer* const buffer,
334  const leRect* const rect,
335  leRect* result);
336 
337 // *****************************************************************************
338 /* Function:
339  leResult lePixelBufferSet(const lePixelBuffer* const buffer,
340  const lePoint* const pnt,
341  leColor color)
342 
343  Summary:
344  Sets a pixel in a pixel buffer at a point to a specified color. Caller is
345  responsible for ensuring that the input color is in the same color format
346  as the pixel buffer.
347 
348  Parameters:
349  const lePixelBuffer* const buffer - the buffer to operate on
350  const lePoint* const - the location of the pixel to set
351  leColor - the color to set the pixel to. must be the same format as the
352  buffer
353 
354  Returns:
355  leResult
356 */
369 LIB_EXPORT leResult lePixelBufferSet(const lePixelBuffer* const buffer,
370  uint32_t x,
371  uint32_t y,
372  leColor color);
373 
374 // *****************************************************************************
375 /* Function:
376  leResult lePixelBufferSet_Unsafe(const lePixelBuffer* const buffer,
377  const lePoint* const pnt,
378  leColor color)
379 
380  Summary:
381  Sets a pixel in a pixel buffer at a point to a specified color. Caller is
382  responsible for ensuring that the input color is in the same color format
383  as the pixel buffer. Like lePixelBufferSet but performs no bounds
384  checking.
385 
386  Parameters:
387  const lePixelBuffer* const buffer - the buffer to operate on
388  const lePoint* const - the location of the pixel to set
389  leColor - the color to set the pixel to. must be the same format as the
390  buffer
391 
392  Returns:
393  leResult
394 */
408 LIB_EXPORT leResult lePixelBufferSet_Unsafe(const lePixelBuffer* const buffer,
409  uint32_t x,
410  uint32_t y,
411  leColor color);
412 
413 // *****************************************************************************
414 /* Function:
415  leResult lePixelBufferAreaFill(const lePixelBuffer* const buffer,
416  uint32_t x,
417  uint32_t y,
418  uint32_t w,
419  uint32_t h,
420  const leColor color)
421 
422  Summary:
423  Fills a rectangular area of a pixel buffer with a solid color.
424 
425  Parameters:
426  const lePixelBuffer* const buffer - the buffer to operate on
427  uint32_t x - the x coordinate of the rectangle to fill
428  uint32_t y - the y coordinate of the rectangle to fill
429  uint32_t w - the width of the rectangle area
430  uint32_t h - the height of the rectangle area
431  const leColor color
432 
433  Returns:
434  leResult - the result of the operation
435 */
447 leResult lePixelBufferAreaFill(const lePixelBuffer* const buffer,
448  uint32_t x,
449  uint32_t y,
450  uint32_t w,
451  uint32_t h,
452  const leColor color);
453 
454 // *****************************************************************************
455 /* Function:
456  leResult lePixelBufferAreaFill_Unsafe(const lePixelBuffer* const buffer,
457  const leRect* const rect,
458  const leColor color)
459 
460  Summary:
461  Fills an area of a pixel buffer with a solid color. Caller is responsible
462  for ensuring that the color is the same color format as the destination
463  buffer. Like lePixelBufferAreaFill but performs no bounds checking.
464 
465  Parameters:
466  const lePixelBuffer* const buffer - the buffer to manipulate
467  const leRect* const rect - the rectangle of the buffer to fill
468  const leColor color - the color to use for the fill operation
469 
470  Returns:
471  leResult
472 */
484 LIB_EXPORT leResult lePixelBufferAreaFill_Unsafe(const lePixelBuffer* const buffer,
485  uint32_t x,
486  uint32_t y,
487  uint32_t w,
488  uint32_t h,
489  leColor color);
490 
491 // *****************************************************************************
492 /* Function:
493  leResult lePixelBufferCopy(lePixelBuffer* dest,
494  int16_t x,
495  int16_t y,
496  const lePixelBuffer* src,
497  leRect* srcRect)
498 
499  Summary:
500  Copies a rectangle of data from one buffer into another buffer. This is
501  a safe copy in that any reads or writes outside of the buffers are detected
502  and discarded. The color data is automatically converted from the source
503  mode to the destination mode.
504 
505  Parameters:
506  lePixelBuffer* dest - the buffer to write to
507  int16_t - the x coordinate to write to
508  int16_t - the y cooridnate to write to
509  const lePixelBuffer* src - the pixel buffer to read from
510  leRect* srcRect - the rectangle of the source data
511 
512  Returns:
513  leResult
514 */
515 leResult lePixelBufferCopy(lePixelBuffer* dest,
516  uint32_t x,
517  uint32_t y,
518  const lePixelBuffer* src,
519  const leRect* srcRect);
520 
521 // *****************************************************************************
522 /* Function:
523  leResult lePixelBuffer_IsLocked(const lePixelBuffer* const buffer)
524 
525  Summary:
526  Returns true if the buffer's lock flag is on.
527 
528  Parameters:
529  const lePixelBuffer* const buffer - the buffer to query
530 
531  Returns:
532  leBool - true if the buffer is locked
533 */
544 LIB_EXPORT leBool lePixelBuffer_IsLocked(const lePixelBuffer* const buffer);
545 
546 // *****************************************************************************
547 /* Function:
548  leResult lePixelBuffer_SetLocked(lePixelBuffer* buffer,
549  leBool locked)
550 
551  Summary:
552  Manipulates a buffer lock flag
553 
554  Parameters:
555  const lePixelBuffer* const buffer - the buffer to query
556  leBool locked - the desired lock state
557 
558  Returns:
559  leResult
560 */
574 LIB_EXPORT leResult lePixelBuffer_SetLocked(lePixelBuffer* buffer,
575  leBool locked);
576 
577 //DOM-IGNORE-BEGIN
578 #ifdef __cplusplus
579  }
580 #endif
581 // DOM-IGNORE-END
582 
583 #endif /* LE_PIXELBUFFER_H */
lePixelBufferGet_Unsafe
LIB_EXPORT leColor lePixelBufferGet_Unsafe(const lePixelBuffer *const buffer, uint32_t x, uint32_t y)
Get pixel at point.
Definition: legato_pixelbuffer.c:279
lePixelBufferSet_Unsafe
LIB_EXPORT leResult lePixelBufferSet_Unsafe(const lePixelBuffer *const buffer, uint32_t x, uint32_t y, leColor color)
Pixel set.
Definition: legato_pixelbuffer.c:347
lePixelBuffer_SetLocked
LIB_EXPORT leResult lePixelBuffer_SetLocked(lePixelBuffer *buffer, leBool locked)
Sets the lock.
Definition: legato_pixelbuffer.c:478
legato_error.h
Error functions, macros and definitions.
leColorModeInfo::size
uint32_t size
Definition: legato_color.h:215
leResult
leResult
This enum represents function call results.
Definition: legato_common.h:134
leColorMode
leColorMode
This enum represents the supported RGB color formats.
Definition: legato_color.h:146
leRect
This struct represents a rectangle.
Definition: legato_common.h:405
legato_color.h
Color definitions and functions.
lePixelBuffer_IsLocked
LIB_EXPORT leBool lePixelBuffer_IsLocked(const lePixelBuffer *const buffer)
Determines the lock state.
Definition: legato_pixelbuffer.c:470
legato_pixelbuffer.h
Pixel Buffer functions and definitions.
leSize::width
int32_t width
Definition: legato_common.h:382
leRectIntersects
LIB_EXPORT leBool leRectIntersects(const leRect *l_rect, const leRect *r_rect)
Determines if two rectangles are intersecting.
Definition: legato_rect.c:51
lePixelBufferGetIndex_Unsafe
LIB_EXPORT leColor lePixelBufferGetIndex_Unsafe(const lePixelBuffer *const buffer, const uint32_t idx)
Get color at index.
Definition: legato_pixelbuffer.c:326
leColorModeInfo::bpp
uint32_t bpp
Definition: legato_color.h:216
lePixelBufferSet
LIB_EXPORT leResult lePixelBufferSet(const lePixelBuffer *const buffer, uint32_t x, uint32_t y, leColor color)
Pixel set.
Definition: legato_pixelbuffer.c:332
leBool
leBool
This enum represents booleans.
Definition: legato_common.h:157
lePixelBufferClipRect
LIB_EXPORT leResult lePixelBufferClipRect(const lePixelBuffer *const buffer, const leRect *const rect, leRect *result)
Clip rectangle.
Definition: legato_pixelbuffer.c:293
leColorModeInfo::bppOrdinal
leBitsPerPixel bppOrdinal
Definition: legato_color.h:217
lePixelBufferOffsetGet_Unsafe
LIB_EXPORT leBuffer lePixelBufferOffsetGet_Unsafe(const lePixelBuffer *const buffer, uint32_t x, uint32_t y)
Get buffer at point.
Definition: legato_pixelbuffer.c:256
LE_FALSE
@ LE_FALSE
Definition: legato_common.h:158
BufferFlags
BufferFlags
leArray data structure definition.
Definition: legato_pixelbuffer.h:66
leSize
This structure is used represents the size of an item.
Definition: legato_common.h:381
legato_rect.h
Rectangle functions and definitions.
leRectClip
LIB_EXPORT void leRectClip(const leRect *l_rect, const leRect *r_rect, leRect *result)
Clips a rectangle to the space of another rectangle.
Definition: legato_rect.c:122
lePixelBufferOffsetGet
LIB_EXPORT leBuffer lePixelBufferOffsetGet(const lePixelBuffer *const buffer, uint32_t x, uint32_t y)
Get buffer at point.
Definition: legato_pixelbuffer.c:237
leColorConvert
LIB_EXPORT leColor leColorConvert(leColorMode mode_in, leColorMode mode_out, leColor color)
Convert to color value.
Definition: legato_color_convert.c:579
lePixelBufferAreaFill
leResult lePixelBufferAreaFill(const lePixelBuffer *const buffer, uint32_t x, uint32_t y, uint32_t w, uint32_t h, const leColor color)
Area fill with checking.
Definition: legato_pixelbuffer.c:364
lePixelBufferGet
LIB_EXPORT leColor lePixelBufferGet(const lePixelBuffer *const buffer, uint32_t x, uint32_t y)
Get pixel at point.
Definition: legato_pixelbuffer.c:269
lePixelBufferAreaFill_Unsafe
LIB_EXPORT leResult lePixelBufferAreaFill_Unsafe(const lePixelBuffer *const buffer, uint32_t x, uint32_t y, uint32_t w, uint32_t h, leColor color)
Area fill no checking.
Definition: legato_pixelbuffer.c:395
LE_TRUE
@ LE_TRUE
Definition: legato_common.h:159
lePixelBufferCreate
LIB_EXPORT leResult lePixelBufferCreate(const int32_t width, const int32_t height, const leColorMode mode, const void *const address, lePixelBuffer *buffer)
Create a pixelbuffer.
Definition: legato_pixelbuffer.c:184
leSize::height
int32_t height
Definition: legato_common.h:383
leBuffer
void * leBuffer
This typedef represents general-purpose buffer.
Definition: legato_common.h:417
leColorInfoTable
const leColorModeInfo leColorInfoTable[]
This array represents information reference table.
Definition: legato_color.c:29
lePixelBuffer
Definition: legato_pixelbuffer.h:91
Generated by   doxygen 1.8.18