Microchip Graphics Suite (MGS) Graphics Canvas API Documentation
Last modified by Microchip on 2024/04/10 15:01
Contents
Introduction
This document provides detailed information on the user-level APIs for Microchip Graphics Suite (MGS) Graphics Canvas.
These APIs are declared in gfx/canvas/gfx_canvas_api.h and defined in gfx/canvas/gfx_canvas_api.c.
APIs
| API | Description | Parameters | Return Value |
| gfxcCreate | Reserves an instance of the canvas object. An instance must be available in the canvas list, otherwise this will fail. gfxcCreate calls are generated automatically to create the Graphics Canvas objects configured using MPLAB Code Configurator® (MCC) Harmony. See gfxcObjectsInitialize() in gfx_canvas.c | None | int - the index of the canvas object if successful -1 if failed |
| gfxcDestroy | Releases a reserved canvas object id and This function does not free up the frame buffer memory. Memory de/allocations are managed separately. | int CanvasID | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcSetPixelBuffer | Initializes the pixel/frame buffer of the canvas | canvasID - the index of the canvas object width - the horizontal resolution of the frame buffer in pixels height - the vertical resolution of the frame buffer in pixels format - the color format of the frame buffer buf - address of the frame buffer | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcCopyBuffer | Copies the contents of a canvas pixelbuffer to another. | srcID - ID of source canvas destID - ID of destination canvas srcRect - rect area in source canvas, must be the same size as destRect destRect - rect area in destination canvas, must be same size srcRect | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcSetBaseCanvasID | Sets the starting canvas ID for all succeeding library layer operations. Ex. All library operations on (layer 1) will target canvas (base + 1). Use API to assign starting canvas ID for a specific screen in a multi-screen project, that way the library can draw to the right canvas for a screen layer. | base - starting canvas ID | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcSetLayer | Sets the display controller layer that will be used to show the canvas. The display controller must support layers for this function to work. | canvasID - the index of the canvas object layerID - the layer index | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcGetlayer | Returns the index of the display controller layer used to display the canvas objects. | canvasID - the index of the canvas object | int - the index of the layer |
| gfxcClearLayer | Resets/Clears the layer assigned to the canvas object. | canvasID - the index of the canvas object | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcSetWindowAlpha | Sets the window alpha value of the canvas. The display controller layer for the canvas must support per-layer, global alpha values. | canvasID - the index of the canvas object alpha - the alpha value | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcSetWindowPosition | Sets the window position of the canvas. The display controller layer for the canvas must support per-layer positioning on the frame. | canvasID - the index of the canvas object xpos - the x position ypos - the y position | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcGetWindowPosition | Gets the window position value of the canvas. The display controller layer for the canvas must support per-layer, positioning of the frame | canvasID - the index of the canvas object xpos - pointer reference to the x position container ypos - pointer reference to the y position container | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcSetWindowSize | Sets the window size for canvas. The display controller layer for the canvas must support per-layer size setting. If the window is smaller than the canvas size, the canvas will be cropped. | canvasID - the index of the canvas object width - the horizontal size height - the vertical size | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcGetWindowSize | Gets the window size for canvas. The display controller layer for the canvas must support per-layer size setting. If the window is smaller than the canvas size, the canvas will be cropped. | canvasID - the index of the canvas object width - pointer reference to the horizontal size container height - pointer reference to the vertical size container | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcSetEffectsCallback | Sets the callback function called to notify of effects status. | canvasID - the index of the canvas object cb - the callback function parm - the callback function parameter | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcSetEffectsInterval | Sets the effects interval. A small interval value will cause the effects to execute faster, and vice versa. | ms - interval in milliseconds | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcShowCanvas | Displays the canvas on the screen. The layer used to display the canvas must be set, otherwise it will not be shown. | canvasID - the index of the canvas object | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcHideCanvas | Hides the canvas. | canvasID - the index of the canvas object | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcCanvasUpdate | Updates the assigned HW layer with the canvas properties. Changes to the canvas object will only be visible after this API is called. | canvasID - the index of the canvas object | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcStartEffectFade | Fades in/out the canvas. A valid display controller layer must be assigned to the canvas, and the layer must support per-layer, global alpha blending | canvasID - the index of the canvas object startAlpha - the starting alpha value endAlpha - the ending alpha value delta - the step value | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcStartEffectMove | Moves the canvas from a start position to the end position using the display controller functions. The layer for the canvas must support window positioning. | canvasID - the index of the canvas object type - the move type startX - the starting x position startY - the starting y position endX - the end x position endY - the end y position delta - the move delta. For FIXED moves, a small delta will move slower. For ACC moves, a small delta will accelerate faster. For DEC moves, a small delta will decelerate faster. | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcStopEffect | Stops the specified effect, if active | canvasID - the index of the canvas object effect - the effect | GFX_SUCCESS - success GFX_FAILURE - fail |
| gfxcGetStatus | Returns the status of the Canvas framework, if any canvas object is busy with pending updates or idle. Use this API to make sure that all canvas update request are done before sending another update request. | None | GFXC_STATUS |
| GFX_CANVAS_Initialize | Initializes the GFX canvas framework. This is automatically generated based on the Graphics Canvas configuration in MCC. | None | void |
| GFX_CANVAS_Task | The canvas task used to manage Graphics Canvas effects. This is automatically generated based on the Graphics Canvas configuration in MCC. | None | void |