/* 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 u_wgl_sbtl.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.
 */
/*----------------------------------------------------------------------------*/

#ifndef _U_WGL_SBTL_H_
#define _U_WGL_SBTL_H_

/*-----------------------------------------------------------------------------
                    include files
 ----------------------------------------------------------------------------*/
#include "u_gl.h"

/*----------------------------------------------------------------------------*/
/*! @defgroup groupMW_WGL_SBTL ISDB DVB Subtitle Widget
  *  @ingroup groupMW_WGL
  *  @brief Provides external function TV Application
  *  %MW Application API would be used by TV Application, lot of these APIs would
  *   be wrapped from Exported API
  *  @see groupMW_WGL_SBTL
  *  @{ 
  */
/*----------------------------------------------------------------------------*/

#ifdef __cplusplus
extern "C" {
#endif

/*-----------------------------------------------------------------------------
                    macros, defines, typedefs, enums
 ----------------------------------------------------------------------------*/
/* commands */
/* WGL_CMD_SBTL_FLIP<HANDLE_T h_page_inst, PTS_T *pui8_pts> */
#define WGL_CMD_SBTL_FLIP                   WGL_MAKE_WIDGET_CMD(HT_WGL_WIDGET_SBTL, 0)    /**< flip data command */

/* WGL_CMD_SBTL_CLEAR_ALL<PTS_T *pui8_pts, NULL> */
#define WGL_CMD_SBTL_CLEAR_ALL              WGL_MAKE_WIDGET_CMD(HT_WGL_WIDGET_SBTL, 1)    /**< clear all command */

/* WGL_CMD_SBTL_UPDATE_LOGI_SIZE<WGL_SBTL_LOGI_T *pt_wgl_sbtl_logi, NULL> */
#define WGL_CMD_SBTL_UPDATE_LOGI_SIZE       WGL_MAKE_WIDGET_CMD(HT_WGL_WIDGET_SBTL,2)    /**< update logical size command */

/* return values */
#define WGL_SBTLR_WOULD_BLOCK                (WGLR_USER + 1)    /**< successful, but can not use it now */
#define WGL_SBTLR_OK                         ((INT32) 0)        /**< successful */
#define WGL_SBTLR_LOCK_ERROR                 ((INT32) -1000)    /**< lock fail */
#define WGL_SBTLR_PIB_NOT_FOUND              ((INT32) -1001)    /**< can not find the PIB */
#define WGL_SBTLR_PIB_RGN_NOT_FOUND          ((INT32) -1002)    /**< can not find the region in PIB */
#define WGL_SBTLR_PIB_RGN_NOT_VALID          ((INT32) -1003)    /**< the PIB region is not vaild */

/* color mode enumeration */
/*------------------------------------------------------------------*/
/*! @enum   WGL_SBTL_COLOR_MODE_T
 *  @brief  This enumeration contains the color mode
 *  @code
 *  typedef enum _WGL_SBTL_COLOR_MODE_T
 *  {
 *      WGL_SBTL_COLOR_MODE_CLUT_2_BIT,
 *      WGL_SBTL_COLOR_MODE_CLUT_4_BIT,
 *      WGL_SBTL_COLOR_MODE_CLUT_8_BIT
 *  } WGL_SBTL_COLOR_MODE_T;    
 *  @endcode
 *  @li@c  WGL_SBTL_COLOR_MODE_CLUT_2_BIT                    - clut 2 bit
 *  @li@c  WGL_SBTL_COLOR_MODE_CLUT_4_BIT                    - clut 4 bit
 *  @li@c  WGL_SBTL_COLOR_MODE_CLUT_8_BIT                    - clut 8 bit
 */
/*------------------------------------------------------------------*/
typedef enum _WGL_SBTL_COLOR_MODE_T
{
    WGL_SBTL_COLOR_MODE_CLUT_2_BIT,
    WGL_SBTL_COLOR_MODE_CLUT_4_BIT,
    WGL_SBTL_COLOR_MODE_CLUT_8_BIT
} WGL_SBTL_COLOR_MODE_T;    

/* PIB locking function */
/*------------------------------------------------------------------*/
/*! @brief This API is called by the Subtitle widget and locks the page instance buffer (PIB) associated by the page instance handle, which is indicated in the argument h_page_inst. The PIB lock is acquired in no-wait manner. If the lock has been acquired by other threads, this API immediately returns WGL_SBTLR_WOULD_BLOCK. If the specified PIB fails to be locked, this API returns WGL_SBTLR_LOCK_ERROR
 *  @param [in]     h_page_inst                     - Contains the subtitle page instance handle
 *  @param [in]     pv_tag                          - Contains the host application private data
 *  @param [out]
 *  @return     Return the error code.
 *  @retval      WGL_SBTLR_OK                   - The specified PIB is successfully locked
 *  @retval      WGL_SBTLR_WOULD_BLOCK          - The specified PIB has been locked by other threads
 *  @retval      WGL_SBTLR_LOCK_ERROR           - The specified PIB fails to be locked
 *  @retval      WGL_SBTLR_PIB_NOT_FOUND        - The specified PIB is not found
 */
/*------------------------------------------------------------------*/
typedef INT32 (*wgl_sbtl_lock_pib_fct)(
    HANDLE_T                h_page_inst,
    VOID                    *pv_tag);

/* PIB unlocking function */
/*------------------------------------------------------------------*/
/*! @brief This API is called by the Subtitle widget and unlocks the page instance buffer (PIB) associated by the page instance handle, which is indicated in the argument h_page_inst.
 *  @param [in]     h_page_inst                     - Contains the subtitle page instance handle
 *  @param [in]     pv_tag                          - Contains the host application private data
 *  @param [out]
 *  @return     Return the error code.
 *  @retval      WGL_SBTLR_OK                   - The specified PIB is successfully unlocked.
 *  @retval      WGL_SBTLR_PIB_NOT_FOUND        - The specified PIB is not found.
 */
/*------------------------------------------------------------------*/
typedef INT32 (*wgl_sbtl_unlock_pib_fct)(
    HANDLE_T                h_page_inst,
    VOID                    *pv_tag);

typedef struct _WGL_SBTL_REGION_T WGL_SBTL_REGION_T;
/*------------------------------------------------------------------*/
/*! @brief This API is called by the Subtitle widget and get a region indicated by ui2_rgn_idx from  the page instance buffer (PIB) associated by the page instance handle, which is indicated in the argument h_page_inst
 *  @param [in]     h_page_inst                     - Contains the subtitle page instance handle
 *  @param [in]     pv_tag                          - Contains the host application private data
 *  @param [in]     ui2_rgn_idx                     - Contains the region index that subtitle widget need
 *  @param [in]     pt_rgn                          - Contains the returned region structure
 *  @param [out]
 *  @return     Return the error code.
 *  @retval      WGL_SBTLR_OK                   - The specified PIB is successfully unlocked.
 *  @retval      WGL_SBTLR_PIB_NOT_FOUND        - The specified PIB is not found.
 *  @retval      WGL_SBTLR_PIB_RGN_NOT_FOUND    - The specified region is not found.
 *  @retval      WGL_SBTLR_PIB_RGN_NOT_VALID    - The specified region is not valid.
 */
/*------------------------------------------------------------------*/
typedef INT32 (*wgl_sbtl_get_page_inst_rgn_fct)(
    HANDLE_T                h_page_inst,
    VOID                    *pv_tag,
    UINT16                  ui2_rgn_idx,
    WGL_SBTL_REGION_T       *pt_rgn);

/*-----------------------------------------------------------------------------
                    structures
 ----------------------------------------------------------------------------*/
/* region structure */
/*------------------------------------------------------------------*/
/*! @struct _WGL_SBTL_REGION_T
 *  @brief  This structure holds the information of a region
 *  @code
 *  struct _WGL_SBTL_REGION_T
 *  {
 *      UINT32                      ui4_rid;
 *      BOOL                        b_dirty;
 *      INT32                       i4_left;
 *      INT32                       i4_top;
 *      UINT32                      ui4_width;
 *      UINT32                      ui4_height;
 *      WGL_SBTL_COLOR_MODE_T       e_clr_mode;
 *      VOID                        *pv_bitmap;
 *      GL_COLOR_T                  *at_clut;
 *      GL_RECT_T                   t_rc_dirty;
 *  };    
 *  @endcode
 *  @li@c  ui4_rid                                           - Contains the region id for identifying the region
 *  @li@c  b_dirty                                           - Contains a BOOL flag indicating the region is dirty or not. If TRUE, the region has to be redrawn and the associated cache buffer (if has) has to be updated
 *  @li@c  i4_left                                           - Contains the location of the left boundary of the region
 *  @li@c  i4_top                                            - Contains the location of the top boundary of the region
 *  @li@c  ui4_width                                         - Contains the width of the region
 *  @li@c  ui4_height                                        - Contains the height of the region
 *  @li@c  e_clr_mode                                        - Contains the color mode of the region
 *  @li@c  *pv_bitmap                                        - Contains the pointer to the bitmap data buffer, which is prepared by the host application of the Subtitle widget (e.g. the Subtitle handler). The size of this buffer must be at least (ui4_width * ui4_height * bits_per_pixel / 8 + 1)
 *  @li@c  *at_clut                                          - Contains the pointer to the region's color lookup table. The size of the color table must be at least 2 ^ (bits_per_pixel).
 *  @li@c  t_rc_dirty                                        - Contains the rectangle of the dirty area in the region. This field is meaningful only when the b_dirty field is TRUE
 */
/*------------------------------------------------------------------*/
struct _WGL_SBTL_REGION_T
{
    UINT32                      ui4_rid;
    BOOL                        b_dirty;
    INT32                       i4_left;
    INT32                       i4_top;
    UINT32                      ui4_width;
    UINT32                      ui4_height;
    WGL_SBTL_COLOR_MODE_T       e_clr_mode;
    VOID                        *pv_bitmap;
    GL_COLOR_T                  *at_clut;
    GL_RECT_T                   t_rc_dirty;
};    

/*------------------------------------------------------------------*/
/*! @struct WGL_SBTL_INIT_T
 *  @brief  This structure holds the information for initializing a Subtitle widget
 *  @code
 *  typedef struct _WGL_SBTL_INIT_T
 *  {
 *      UINT32                              ui4_page_width;
 *      UINT32                              ui4_page_height;
 *      wgl_sbtl_lock_pib_fct               pf_lock_pib;
 *      VOID*                               pv_tag_lock_pib;
 *      wgl_sbtl_unlock_pib_fct             pf_unlock_pib;
 *      VOID*                               pv_tag_unlock_pib;
 *      wgl_sbtl_get_page_inst_rgn_fct      pf_get_page_inst_rgn;
 *      VOID*                               pv_tag_get_rgn;
 *  } WGL_SBTL_INIT_T;    
 *  @endcode
 *  @li@c  ui4_page_width                                    - Contains the logical width of a subtitling page. Note that if the logical width is not the same as the physical width of the Subtitle widget, the page content would be automatically scaled to fit into the physical widget area
 *  @li@c  ui4_page_height                                   - Contains the logical height of a subtitling page. Note that if the logical height is not the same as the physical height of the Subtitle widget, the page content would be automatically scaled to fit into the physical widget area
 *  @li@c  pf_lock_pib                                       - Contains the pointer of a lock function that is used to acquire and lock the page instance buffer. This function is provided by the host application of the Subtitle widget and will be called before a PIB is to be used. For more information about this function, refer to (*wgl_sbtl_lock_pib_fct)
 *  @li@c  pv_tag_lock_pib                                   - Contains the host application private data, when pf_lock_pib is called,  it will be transferred to subtitle handler as parameter
 *  @li@c  pf_unlock_pib                                     - Contains the pointer of an unlock function that is used to unlock the page instance buffer. This function is provided by the host application of the Subtitle widget and will be called if a PIB can be freed. For more information about this function, refer to (*wgl_sbtl_unlock_pib_fct)(*wgl_sbtl_lock_pib_fct).
 *  @li@c  pv_tag_unlock_pib                                 - Contains the host application private data, when pf_unlock_pib is called,  it will be transferred to subtitle handler as parameter
 *  @li@c  pf_get_page_inst_rgn                              - Contains the pointer of an get region function that is used to get region list from one page instance. This function is provided by the host application of the Subtitle widget and will be called if a PIB can be freed. For more information about this function
 *  @li@c  pv_tag_get_rgn                                    - Contains the host application private data, when pf_get_page_inst_rgn is called,  it will be transferred to subtitle handler as parameter
 */
/*------------------------------------------------------------------*/
typedef struct _WGL_SBTL_INIT_T
{
    UINT32                              ui4_page_width;
    UINT32                              ui4_page_height;
    wgl_sbtl_lock_pib_fct               pf_lock_pib;
    VOID*                               pv_tag_lock_pib;
    wgl_sbtl_unlock_pib_fct             pf_unlock_pib;
    VOID*                               pv_tag_unlock_pib;
    wgl_sbtl_get_page_inst_rgn_fct      pf_get_page_inst_rgn;
    VOID*                               pv_tag_get_rgn;
} WGL_SBTL_INIT_T;    

/*------------------------------------------------------------------*/
/*! @struct WGL_SBTL_LOGI_SZ_T
 *  @brief  This structure contains the DDS information for logical size display
 *  @code
 *  typedef struct _WGL_SBTL_LOGI_SZ_T
 *  {
 *      UINT16      ui2_logi_width;
 *      UINT16      ui2_logi_height;
 *  } WGL_SBTL_LOGI_SZ_T;
 *  @endcode
 *  @li@c  ui2_logi_width                                    - Contains new logical width of a subtitling page. Note that if the logical width is not the same as the physical width of the Subtitle widget, the page content would be automatically scaled to fit into the physical widget area.
 *  @li@c  ui2_logi_height                                   - Contains new logical height of a subtitling page. Note that if the logical height is not the same as the physical height of the Subtitle widget, the page content would be automatically scaled to fit into the physical widget area.
 */
/*------------------------------------------------------------------*/
typedef struct _WGL_SBTL_LOGI_SZ_T
{
    UINT16      ui2_logi_width;
    UINT16      ui2_logi_height;
} WGL_SBTL_LOGI_SZ_T;


#ifdef __cplusplus
}
#endif

#endif

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


