/* SPDX-License-Identifier: LGPL-2.1-only OR BSD-3-Clause */
/******************************************************************************
 *
 * This file is provided under a dual license.  When you use or
 * distribute this software, you may choose to be licensed under
 * version 2.1 of the GNU Lesser General Public License
 * ("LGPLv2.1 License") or BSD License.
 *
 * LGPLv2.1 License
 *
 * Copyright(C) 2019 MediaTek Inc.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of version 2.1 of the GNU Lesser General Public
 * License as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html for more
 * details.
 *
 * BSD LICENSE
 *
 * Copyright(C) 2019 MediaTek Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *  * Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *  * Neither the name of the copyright holder nor the names of its
 *    contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *****************************************************************************/

/*----------------------------------------------------------------------------*/
/*! @file c_wgl_image.h 
 *  $RCSfile: $
 *  $Revision: #1 $
 *  $Date: 2015/05/29 $
 *  $Author: brianpc.huang $
 *  
 *  @par Description:
 *         This header file contains public interfaces, constant and type 
 *         definitions of the Widget Library.
 */
/*----------------------------------------------------------------------------*/
/*----------------------------------------------------------------------------*/
/*! @addtogroup groupMW_WGL
 *  @{ 
 */
/*----------------------------------------------------------------------------*/

 
#ifndef _C_WGL_IMAGE_H_
#define _C_WGL_IMAGE_H_

/*-----------------------------------------------------------------------------
                    include files
 ----------------------------------------------------------------------------*/
#include "u_wgl_image.h"
#include "u_wgl_cvsst.h"

#ifdef __cplusplus
extern "C" {
#endif

/*-----------------------------------------------------------------------------
                    macros, defines, typedefs, enums
 ----------------------------------------------------------------------------*/

/*-----------------------------------------------------------------------------
                    structures
 ----------------------------------------------------------------------------*/

/*-----------------------------------------------------------------------------
                    functions
 ----------------------------------------------------------------------------*/
/*------------------------------------------------------------------*/
/*! @brief This function returns target image template's width and height.
 *  @param [in]  h_img_tpl	Handle of a image template.
 *  @param [out]   pui4_width  Pointer to a UINT32 variable to receive target template's width.
 *  @param [out]   pui4_height Pointer to a UINT32 variable to receive target template's height.
 *  @note
 *  @see
 *  @return  return error code
 *  @retval   WGLR_OK The routine was successful.
 *  @retval   WGLR_INV_ARG    The argument h_img_tpl, pui4_width, or pui4_height is NULL.
 *  @retval   WGLR_INV_HANDLE The h_img_tpl is invalid handle.
 *  @retval   WGLR_INTERNAL_ERROR The image handle and image data kept in widget library is invalid
 *  @retval      -
 */
/*------------------------------------------------------------------*/
extern INT32 c_wgl_img_tpl_get_size(
        WGL_HIMG_TPL_T                  h_img_tpl,
        UINT32*                         pui4_width,
        UINT32*                         pui4_height);

/*------------------------------------------------------------------*/
/*! @brief This function creates an image template for assigned image.
 *  @param [in]   e_segment_type  Segment type of the assigned image. 
 *  @param [in]   pt_image    Pointer to a WGL_IMG_T structure that contains a image data. 
 *  @param [out] ph_img_tpl	Pointer to a WGL_HIMG_TPL_T variable to receive the image template handle.
 *  @note
 *  @see
 *  @return  return error code
 *  @retval    WGLR_OK The routine was successful.
 *  @retval    WGLR_INV_ARG    The followed table lists the cases that may cause this error:
 *                 pt_image:   NULL
 *                 ph_img_tpl: NULL
 *                ui2_width of pt_image:  0
 *                 ui2_lines of pt_image:  0
 *                  pui1_image_data of pt_image: NULL
 *                  ui4_image_size of pt_image:  0
 *  @retval WGLR_NOT_SUPPORT_FORMAT The followed table lists the cases that may cause this error:
 *                  ui1_bits_per_pixel of pt_image: Not 16
 *                  ui2_table_columns of pt_image:  Not 0
 *                  pt_table_data of pt_image:  Not NULL
 *                  ui1_image_type of pt_image: WGL_IMG_TYPE_JPG or other undefined type
 *  @retval  WGLR_INTERNAL_ERROR The image handle and image data kept in widget library is invalid
 *  @retval  WGLR_OUT_OF_MEMORY  There isn't sufficient memory.
 *  @retval  WGLR_OUT_OF_HANDLES There isn't enough handles or the caller's  handle resource is exhausted.
 *  @retval  WGLR_SYS_RC_CREATE_FAIL Fail to create surface for this image template.
 *  @retval  WGLR_INTERNAL_ERROR Fail to get the surface information for this image template.
 *  @retval  WGLR_LOCK_ERROR Fail to lock the surface for some internal operation.
 *  @retval  WGLR_UNLOCK_ERROR   Fail to unlock the surface to end this routine.
 *  @retval      -
 */
/*------------------------------------------------------------------*/
extern INT32 c_wgl_img_tpl_create(
        WGL_IMG_ST_T                    e_segment_type,
        const WGL_IMG_T*                pt_image,
        WGL_HIMG_TPL_T*                 ph_img_tpl);
/*------------------------------------------------------------------*/
/*! @brief This function creates an image template for assigned image. If the image is compressed, this function willd decompress it.
 *  @param [in]   e_segment_type  Segment type of the assigned image. 
 *  @param [in]   pt_image    Pointer to a WGL_IMG_T structure that contains a image data. 
 *  @param [out] ph_img_tpl	Pointer to a WGL_HIMG_TPL_T variable to receive the image template handle.
 *  @return  return error code
 *  @retval    WGLR_OK The routine was successful.
 *  @retval    WGLR_INV_ARG    The followed table lists the cases that may cause this error:
 *                 pt_image:   NULL
 *                 ph_img_tpl: NULL
 *                ui2_width of pt_image:  0
 *                 ui2_lines of pt_image:  0
 *                  pui1_image_data of pt_image: NULL
 *                  ui4_image_size of pt_image:  0
 *  @retval WGLR_NOT_SUPPORT_FORMAT The followed table lists the cases that may cause this error:
 *                  ui1_bits_per_pixel of pt_image: Not 16
 *                  ui2_table_columns of pt_image:  Not 0
 *                  pt_table_data of pt_image:  Not NULL
 *                  ui1_image_type of pt_image: WGL_IMG_TYPE_JPG or other undefined type
 *  @retval  WGLR_INTERNAL_ERROR The image handle and image data kept in widget library is invalid
 *  @retval  WGLR_OUT_OF_MEMORY  There isn't sufficient memory.
 *  @retval  WGLR_OUT_OF_HANDLES There isn't enough handles or the caller's  handle resource is exhausted.
 *  @retval  WGLR_SYS_RC_CREATE_FAIL Fail to create surface for this image template.
 *  @retval  WGLR_INTERNAL_ERROR Fail to get the surface information for this image template.
 *  @retval  WGLR_LOCK_ERROR Fail to lock the surface for some internal operation.
 *  @retval  WGLR_UNLOCK_ERROR   Fail to unlock the surface to end this routine.
 *  @retval      -
 */
/*------------------------------------------------------------------*/

extern INT32 c_wgl_img_tpl_create_ex(
        WGL_IMG_ST_T                    e_segment_type,
        const WGL_IMG_T*                pt_image,
        WGL_HIMG_TPL_T*                 ph_img_tpl);


/*------------------------------------------------------------------*/
/*! @brief  This function destroys the input image template.
 *  @param [in]  h_img_tpl	Handle of a image template.
 *  @param [out]  None
 *  @note
 *  @see
 *  @return  return error code
 *  @retval    WGLR_OK The routine was successful.
 *  @retval    WGLR_INV_ARG    The h_img_tpl is NULL or invalid.
 *  @retval     WGLR_INTERNAL_ERROR The internal object for the image template is NULL or fail to free this object.
 *  @retval     WGLR_SYS_RC_CANNOT_FREE The image template is provided and maintained by the system. 
 *  @retval      -
 */
/*------------------------------------------------------------------*/
extern INT32 c_wgl_img_tpl_destroy(
        WGL_HIMG_TPL_T                  h_img_tpl);


/*------------------------------------------------------------------*/
/*! @brief This API is to create surface by input image template.
  *  @param [in]  h_img_tpl	Handle of a image template.
 *  @param [in]   pe_type    Segment type of the assigned image. 
 *  @param [out] ph_surface Pointer to a surface handle created according to h_img_tpl .
 *  @note
 *  @see
 *  @return  return error code
 *  @retval    WGLR_OK The routine was successful.
 *  @retval    WGLR_INV_ARG    The followed table lists the cases that may cause this error:
 *                 h_img_tpl:   NULL
 *                 pe_type: NULL
 *                  ph_surface: NULL
 *  @retval  WGLR_INTERNAL_ERROR The image handle and image data kept in widget library is invalid
 *  @retval  WGLR_OUT_OF_MEMORY  There isn't sufficient memory.
 *  @retval  WGLR_OUT_OF_HANDLES There isn't enough handles or the caller's  handle resource is exhausted.
 *  @retval  WGLR_SYS_RC_CREATE_FAIL Fail to create surface for this image template.
 *  @retval  WGLR_INTERNAL_ERROR Fail to get the surface information for this image template.
 *  @retval  WGLR_LOCK_ERROR Fail to lock the surface for some internal operation.
 *  @retval  WGLR_UNLOCK_ERROR   Fail to unlock the surface to end this routine.
 *  @retval   WGLR_IMG_DRAW_FAIL   -Dram the surface data fail.
 */
/*------------------------------------------------------------------*/
extern INT32 c_wgl_img_tpl_image_data_clone(
        WGL_HIMG_TPL_T                      h_img_tpl,
        WGL_IMG_ST_T*                       pe_type,
        GL_HSURFACE_T*                      ph_surface);

/*------------------------------------------------------------------*/
/*! @brief This API is to create an image template by surface information.
  *  @param [in]   e_segment_type  Segment type of the assigned image. 
 *  @param [in]   h_src_surf    Source surface handle to create image template
 *  @param [out] ph_img_tpl	Pointer to a WGL_HIMG_TPL_T variable to receive the image template handle.
 *  @note
 *  @see
 *  @return  return error code
 *  @retval    WGLR_OK The routine was successful.
 *  @retval    WGLR_INV_ARG    The followed table lists the cases that may cause this error:
 *                 h_src_surf:   NULL
 *                 ph_img_tpl: NULL
 *  @retval     WGLR_INTERNAL_ERROR Some internal calls return error.
 *  @retval   WGLR_IMG_DRAW_FAIL   -Dram the surface data fail.
 *  @retval  WGLR_OUT_OF_HANDLES There isn't enough handles or the caller's  handle resource is exhausted.
 */
/*------------------------------------------------------------------*/
extern INT32 c_wgl_img_tpl_create_by_surf(
        WGL_IMG_ST_T                    e_segment_type,
        GL_HSURFACE_T                   h_src_surf,
        WGL_HIMG_TPL_T*                 ph_img_tpl);

/*------------------------------------------------------------------*/
/*! @brief This API renders the widget which is located in h_graphics with input WGL_HIMG_TPL_T value. Note that the region is specified in the local coordinates of h_widget.
 *  @param [in]    h_img_tpl             Contains the image handle used to paint on the widget.
 *  @param [in]  pt_output_rect         Contains the rectangle of the widget.
 *  @param [in]  pt_invalid_rect        Contains the invalid rectangle of the widget.
 *  @param [in]  h_graphics              Contains the pointer to the graphic context that can be used to paint the widget background.
 *  @param [in]  pt_cvsst                Contains the canvas status info of the widget.
 *  @param [in]  e_paint_method     Contains the paint mode
 *  @param [out]  None
 *  @note
 *  @see
 *  @return  return error code
 *  @retval    WGLR_OK The routine was successful. 
*  @retval    WGLR_INV_ARG    One of input arguments is NULL.
*  @retval   WGLR_NOT_SUPPORT_FORMAT The image format is not supported.
*  @retval   WGLR_INTERNAL_ERROR  Some internal calls return error.
 *  @retval      -
 */
/*------------------------------------------------------------------*/
extern INT32 c_wgl_img_tpl_paint(
        WGL_HIMG_TPL_T             h_img_tpl,
        const GL_RECT_T*           pt_output_rect,
        const GL_RECT_T*           pt_invalid_rect,
        GL_HGRAPHICS_T             h_graphics,
        const WGL_CANVAS_STATUS_T  *pt_cvsst,
        WGL_TPL_PAINT_METHOD_T     e_paint_method);

/*------------------------------------------------------------------*/
/*! @brief This API is to update image region by surface information.
 *  @param [in] h_dest_img_tpl          -The destignation image handle.
 *  @param [in] h_src_surf                 -The source surface handle.
 *  @param [out] None
 *  @note
 *  @see
 *  @return  return error code
 *  @retval    WGLR_OK The routine was successful. 
*  @retval    WGLR_INV_ARG    -One of input arguments is NULL.
*  @retval   WGLR_INTERNAL_ERROR    -The image handle is invalid.
*  @retval   WGLR_INV_CMD    -if this image template is in the compressed format, it can not be updated by a surface..
*  @retval   WGLR_IMG_DRAW_FAIL   -Dram the surface data fail.
 *  @retval      -
 */
/*------------------------------------------------------------------*/
extern INT32 c_wgl_img_tpl_update_by_surf(
        WGL_HIMG_TPL_T                  h_dest_img_tpl,
        GL_HSURFACE_T                   h_src_surf);


extern INT32 c_wgl_img_tpl_create_surface(
        const WGL_HIMG_TPL_T*                  ph_img_tpl,
        UINT16                                 ui2_img_nbs);

extern INT32 c_wgl_img_tpl_destroy_surface(
        const WGL_HIMG_TPL_T*                  ph_img_tpl,
        UINT16                                 ui2_img_nbs);

extern INT32 c_wgl_img_cache_flush(VOID);


extern INT32 c_wgl_set_img_decode_function(WGL_IMG_DECODE_FUNCTION_TABLE_T* pt_dec_table);

extern INT32 c_wgl_set_invert_height(WGL_HIMG_TPL_T                          h_img_tpl,
                                     UINT16                                  ui2_invert_lines);

extern INT32 c_wgl_set_image_decode_sw_force(BOOL fg_sw);

#ifdef __cplusplus
}
#endif

#endif

/*----------------------------------------------------------------------------*/
/*! @} */   /* end of  groupMW_WGL*/
/*----------------------------------------------------------------------------*/


