gfx_canvas_api.h

Go to the documentation of this file.

// DOM-IGNORE-BEGIN
/*******************************************************************************
* Copyright (C) 2020 Microchip Technology Inc. and its subsidiaries.
*
* Subject to your compliance with these terms, you may use Microchip software
* and any derivatives exclusively with Microchip products. It is your
* responsibility to comply with third party license terms applicable to your
* use of third party software (including open source software) that may
* accompany Microchip software.
*
* THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, WHETHER
* EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, INCLUDING ANY IMPLIED
* WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A
* PARTICULAR PURPOSE.
*
* IN NO EVENT WILL MICROCHIP BE LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE,
* INCIDENTAL OR CONSEQUENTIAL LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND
* WHATSOEVER RELATED TO THE SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS
* BEEN ADVISED OF THE POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE
* FULLEST EXTENT ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN
* ANY WAY RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY,
* THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.
*******************************************************************************/
// DOM-IGNORE-END

/*******************************************************************************
GFX GLCD Driver Interface Declarations for Static Single Instance Driver

Company:
Microchip Technology Inc.

File Name:
gfx_canvas_api.h

Summary:
GFX Canvas Virtual Display Component private header file

Description:
The GFX Canvas provides a virtual display driver interface.

Remarks:
None
*******************************************************************************/

#ifndef _GFX_CANVAS_API_H    /* Guard against multiple inclusion */
#define _GFX_CANVAS_API_H

#include "gfx/driver/gfx_driver.h"

// DOM-IGNORE-BEGIN
#ifdef __cplusplus  // Provide C++ Compatibility
extern "C" {
#endif
    // DOM-IGNORE-END

#define GFXC_COLOR_FORMAT gfxColorMode 
#define GFXC_RESULT gfxResult

    // *****************************************************************************
    /* Enumeration:
    GFXC_FX_TYPE

    Summary:
    Canvas effects types
    */
    typedef enum
    {
        GFXC_FX_FADE,       //Fade effect
        GFXC_FX_MOVE,       //Move effect
    } GFXC_FX_TYPE;

    // *****************************************************************************
    /* Enumeration:
    GFXC_STATUS

    Summary:
    Canvas status types
    */
    typedef enum
    {
        GFXC_STAT_IDLE = 0,
        GFXC_STAT_BUSY,
    } GFXC_STATUS;

    // *****************************************************************************
    /* Enumeration:
    GFXC_FX_MOVE_TYPE

    Summary:
    Canvas move effects type.
    */
    typedef enum
    {
        GFXC_FX_MOVE_FIXED,      //Fixed speed move
        GFXC_FX_MOVE_ACC,       //Accelerating move
        GFXC_FX_MOVE_DEC,       //Decelerating move
    } GFXC_FX_MOVE_TYPE;

    // *****************************************************************************
    /* Enumeration:
    GFXC_FX_STATUS

    Summary:
    Canvas effects status.
    */
    typedef enum
    {
        GFXC_FX_IDLE,                   //Done or idle, no active effects
        GFXC_FX_DONE = GFXC_FX_IDLE,
        GFXC_FX_START,                  //Starting effect
        GFXC_FX_RUN,                    //effect in progress
    } GFXC_FX_STATUS;

    typedef void(*gfxcCallback) (unsigned int canvasID,
        GFXC_FX_TYPE effect,
        GFXC_FX_STATUS status,
        void * parm);

    extern const gfxDisplayDriver gfxDriverInterface;

    // *****************************************************************************
    /* Function:
    int gfxcCreate(void);

    Summary:
    Reserves an instance of the canvas object. An instance must be available
    in the canvas list, otherwise this will fail.

    Parameters:
    None

    Returns:
    int - the index of the canvas object if successful, -1 if failed
    */
    int gfxcCreate(void);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcDestroy(unsigned int canvasID);

    Summary:
    Releases a reserved canvas object and makes it available

    Parameters:
    canvasID - the index of the canvas object

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcDestroy(unsigned int canvasID);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcSetPixelBuffer(unsigned int canvasID,
    unsigned int width,
    unsigned int height,
    const GFXC_COLOR_FORMAT format,
    void * buf);

    Summary:
    Initializes the pixel/frame buffer of the canvas

    Parameters:
    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 in pixels
    buf - address of the frame buffer

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcSetPixelBuffer(unsigned int canvasID,
        unsigned int width,
        unsigned int height,
        const GFXC_COLOR_FORMAT format,
        void * buf);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcCopyBuffer(unsigned int srcID,
    unsigned int destID,
    const gfxRect * srcRect,
    const gfxRect * destRect);

    Summary:
    Copies the contents of a canvas pixelbuffer to another

    Parameters:
    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

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcCopyBuffer(unsigned int srcID,
        unsigned int destID,
        const gfxRect * srcRect,
        const gfxRect * destRect);


    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcSetBaseCanvasID(unsigned int base)

    Summary:
    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.

    Parameters:
    base - starting canvas ID

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcSetBaseCanvasID(unsigned int base);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcSetLayer(unsigned int canvasID, unsigned int layerID);

    Summary:
    Sets the display controller layer that will be used to show the canvas. The
    display controller must support layers for this function to work.

    Parameters:
    canvasID - the index of the canvas object
    layerID - the layer index

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcSetLayer(unsigned int canvasID, unsigned int layerID);

    // *****************************************************************************
    /* Function:
    int gfxcGetlayer(unsigned int canvasID);

    Summary:
    Returns the index of the layer used to display the canvas objects

    Parameters:
    canvasID - the index of the canvas object

    Returns:
    int - the index of the layer
    */
    int gfxcGetlayer(unsigned int canvasID);

    // *****************************************************************************
    /* Function:
    int gfxcClearLayer(unsigned int canvasID);

    Summary:
    Resets/Clears the layer assigned to the canvas object.

    Parameters:
    canvasID - the index of the canvas object

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcClearLayer(unsigned int canvasID);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcSetWindowAlpha(unsigned int canvasID, uint8_t alpha);

    Summary:
    Sets the window alpha value of the canvas. The display controller layer for
    the canvas must support per-layer, global alpha values

    Parameters:
    canvasID - the index of the canvas object
    alpha - the alpha value

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcSetWindowAlpha(unsigned int canvasID, uint8_t alpha);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcSetWindowPosition(unsigned int canvasID, int xpos, int ypos);

    Summary:
    Sets the window alpha value of the canvas. The display controller layer for
    the canvas must support per-layer, positioning of the frame

    Parameters:
    canvasID - the index of the canvas object
    xpos - the x position
    ypos - the y position

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcSetWindowPosition(unsigned int canvasID, int xpos, int ypos);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcGetWindowPosition(unsigned int canvasID, int* xpos, int* ypos);

    Summary:
    Gets the window position value of the canvas. The display controller layer for
    the canvas must support per-layer, positioning of the frame

    Parameters:
    canvasID - the index of the canvas object
    xpos - pointer reference to the x position container
    ypos - pointer reference to the y position container

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcGetWindowPosition(unsigned int canvasID, int* xpos, int* ypos);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcSetWindowSize(unsigned int canvasID,
    unsigned int width,
    unsigned int height);

    Summary:
    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

    Parameters:
    canvasID - the index of the canvas object
    width - the horizontal size
    height - the vertical size

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcSetWindowSize(unsigned int canvasID, unsigned int width, unsigned int height);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcGetWindowSize(unsigned int canvasID,
    unsigned int* width,
    unsigned int* height);

    Summary:
    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

    Parameters:
    canvasID - the index of the canvas object
    width - pointer reference to the horizontal size container
    height - pointer reference to the vertical size container

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcGetWindowSize(unsigned int canvasID, unsigned int* width, unsigned int* height);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcSetEffectsCallback(unsigned int canvasID, gfxcCallback cb, void * parm);

    Summary:
    Sets the callback function called to notify of effects status

    Parameters:
    canvasID - the index of the canvas object
    cb - the callback function
    parm - the callback function parameter

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcSetEffectsCallback(unsigned int canvasID, gfxcCallback cb, void * parm);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcShowCanvas(unsigned int canvasID);

    Summary:
    Displays the canvas on the screen. The layer used to display the canvas must
    be set, otherwise it will not be shown.

    Parameters:
    canvasID - the index of the canvas object

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcShowCanvas(unsigned int canvasID);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcHideCanvas(unsigned int canvasID);

    Summary:
    Hides the canvas

    Parameters:
    canvasID - the index of the canvas object

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcHideCanvas(unsigned int canvasID);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcCanvasUpdate(unsigned int canvasID);

    Summary:
    Updates the assigned layer with the canvas properties

    Parameters:
    canvasID - the index of the canvas object

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcCanvasUpdate(unsigned int canvasID);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcStartEffectFade(unsigned int canvasID,
    uint8_t startAlpha,
    uint8_t endAlpha,
    uint8_t delta);

    Summary:
    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

    Parameters:
    canvasID - the index of the canvas object
    startAlpha - the starting alpha value
    endAlpha - the ending alpha value
    delta - the step value

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcStartEffectFade(unsigned int canvasID,
        uint8_t startAlpha,
        uint8_t endAlpha,
        uint8_t delta);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcStartEffectMove(unsigned int canvasID,
    GFXC_FX_MOVE_TYPE type,
    int startX, int startY,
    int endX,
    int endY,
    unsigned int delta);

    Summary:
    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.

    Parameters:
    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.

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcStartEffectMove(unsigned int canvasID,
        GFXC_FX_MOVE_TYPE type,
        int startX,
        int startY,
        int endX,
        int endY,
        unsigned int delta);

    // *****************************************************************************
    /* Function:
    GFXC_RESULT gfxcStopEffect(unsigned int canvasID, GFXC_FX_TYPE effect);

    Summary:
    Stops the specified effect, if active

    Parameters:
    canvasID - the index of the canvas object
    effect - the effect

    Returns:
    GFX_SUCCESS - success
    GFX_FAILURE - fail
    */
    GFXC_RESULT gfxcStopEffect(unsigned int canvasID, GFXC_FX_TYPE effect);

    // *****************************************************************************
    /* Function:
    GFXC_STATUS gfxcGetStatus(void);

    Summary:
    Returns the status of the Canvas framework, if any canvas object is busy
    with pending updates or idle. Use to make sure that all canvas update request
    are done before sending another update request.

    Parameters:
    None

    Returns:
    GFXC_STATUS
    */
    GFXC_STATUS gfxcGetStatus(void);

    // *****************************************************************************
    /* Function:
    void GFX_CANVAS_Initialize(void);

    Summary:
    Initializes the GFX canvas framework

    Parameters:
    None

    Returns:
    None
    */
    void GFX_CANVAS_Initialize(void);

    // *****************************************************************************
    /* Function:
    void GFX_CANVAS_Task(void);

    Summary:
    The canvas task

    Parameters:
    None

    Returns:
    None
    */
    void GFX_CANVAS_Task(void);

    /* Provide C++ Compatibility */
#ifdef __cplusplus
}
#endif

#endif /* _GFX_CANVAS_API_H */

/* *****************************************************************************
End of File
*/