/*
 * Copyright 2010 Trident Microsystems (Far East) Ltd. All rights reserved.
 * All prior copyright rights in this work and the accompanying software
 * products transferred to Trident Microsystems (Far East) Ltd. by written
 * agreement.
 */
/*****************************************************************************/
/* Copyright (c) 2010 NXP B.V.  All rights are 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 NXP 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      */
/* OWNER 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   phStbVideoRenderer_Layer.h
    @brief  Video Renderer Component

    Layer API for the Video Renderer.
*//*

Rev Date        Author      Comments
--------------------------------------------------------------------------------
  1 20060613    burningh    Import v20 from STB810 and mod for STB225
  2 20061114    burningh    Add SetBufferPointer method (for Osd layers)
  3 20061207    burningh    Add clarification about rectangles
  4 20070808    neill       Add layer alpha blending get/set
  5 20070921    neill       Add support for HD framebuffers
  6 20070927    neill       Add video buffer device support
  7 20071123    burningh    Improve documentation of top level APIs
  8 20071207    neill       Add flicker filtering support
  9 20080709    neill       Add force param to blank output and set blank IOCTL
 10 20081014    neill       Add phStbVideoRenderer_Layer_SubmitVideoFrame
 11 20081219    neill       Add support for multiple graphics modes
 12 20090116    neill       Add progressive flag for submitting video frames
 13 20090120    batelaan    Update file copyright/license text
 14 20090306    mpage       Add phStbVideoRenderer_Layer_GetVideoFrameInfo.
--------------------------------------------------------------------------------
    For consistency and standardisation retain the Section Separators.
*/

#ifndef PHSTBVIDEORENDERER_LAYER_H
#define PHSTBVIDEORENDERER_LAYER_H

/**************************************************************
* INCLUDE FILES                                               *
***************************************************************/

#include <tmNxTypes.h>

#ifdef __cplusplus
extern "C"
{
#endif

/**************************************************************
* EXPORTED MACROS                                             *
***************************************************************/

/** Default brightness value. */
#define PH_STBVIDEORENDERER_LAYER_DEFAULT_BRIGHTNESS 0U

/** Default contrast value. */
#define PH_STBVIDEORENDERER_LAYER_DEFAULT_CONTRAST   255U

/** Default saturation value. */
#define PH_STBVIDEORENDERER_LAYER_DEFAULT_SATURATION 255U

/** Minimum rectangle parameter size. */
#define PH_STBVIDEORENDERER_LAYER_MIN_RECT_SIZE      (64U)

/**************************************************************
* EXPORTED TYPEDEFS                                           *
***************************************************************/

/** @brief Opaque type definition for a layer . */
typedef struct phStbVideoRenderer_Layer phStbVideoRenderer_Layer_t;

/** @brief Describes a layer's possible input format. */
typedef enum phStbVideoRenderer_Layer_InputFormat
{
    /** No memory allocated in the packet buffers. */
    phStbVideoRenderer_Layer_InputFormatNone = 0,
    /** Memory allocated in packet buffers to cater for SD use cases. */
    phStbVideoRenderer_Layer_InputFormatSD,
    /** Memory allocated in packet buffers to cater for HD and SD use cases. */
    phStbVideoRenderer_Layer_InputFormatHD,
    /** Number of IOD formats. */
    phStbVideoRenderer_Layer_InputFormatCount
} phStbVideoRenderer_Layer_InputFormat_t;

typedef enum phStbVideoRenderer_GfxMode
{
    phStbVideoRenderer_GfxMode_Clut256,
    phStbVideoRenderer_GfxMode_RGB565,
    phStbVideoRenderer_GfxMode_ARGB1555,
    phStbVideoRenderer_GfxMode_ARGB4444,
    phStbVideoRenderer_GfxMode_ARGB8888,
    phStbVideoRenderer_GfxMode_Invalid
}phStbVideoRenderer_GfxMode_t;

typedef struct phStbVideoRenderer_GfxClut
{
    /* The total number of enttries in the CLUT */
    UInt32 gfxClutSize;
    /* Index in CLUT where the init data starts */
    UInt32 gfxClutStart;
    /* CLUT data */
    UInt32 gfxClutData[256];

} phStbVideoRenderer_GfxClut_t;

/**************************************************************
* EXPORTED DATA                                               *
***************************************************************/

/**************************************************************
* EXPORTED FUNCTION PROTOTYPES                                *
***************************************************************/

/******************************************************************************/
/** Used to get the clock id for my clock handle.

    @param pInstance @b IN The layer instance for the layer.
    @param pClockId  @b OUT Pointer to storage for the ID of my clock handle.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    @see phStbClock

    NAB TODO: We don't yet have a spec for the AV sync mechanism; it's being handled by Caen
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetClockId(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t *pClockId);

/******************************************************************************/
/** Used to blank or unblank a layer.

    @param pInstance @b IN The layer instance for the layer.
    @param blank @b IN  true to blank
                        false to unblank.
    @param force @b IN  force the action immediately

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

*/
extern tmErrorCode_t phStbVideoRenderer_Layer_BlankOutput(
    phStbVideoRenderer_Layer_t *pInstance,
    bool blank,
    bool force);

/******************************************************************************/
/** Used to submit a new video frame.

    @param pInstance @b IN The layer instance for the layer.
    @param yData     @b IN Address of buffer containing Y data
    @param uvData    @b IN Address of buffer containing UV data
    @param width     @b IN Width of frame
    @param height    @b IN Height of frame
    @param progressive @b IN true = progressive format, false = interlaced format

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SubmitVideoFrame(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t yData,
    uint32_t uvData,
    uint32_t width,
    uint32_t height,
    bool progressive);

/******************************************************************************/
/** Used to get info about the current video frame.

    @param pInstance @b IN The layer instance for the layer.
    @param pYData     @b OUT Address of buffer containing Y data
    @param pUVData    @b OUT Address of buffer containing UV data
    @param pWidth     @b OUT Width of frame
    @param pHeight    @b OUT Height of frame
    @param pProgressive @b OUT true = progressive format, false = interlaced format

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetVideoFrameInfo(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t *pYData,
    uint32_t *pUVData,
    uint32_t *pWidth,
    uint32_t *pHeight,
    bool *pProgressive);

/******************************************************************************/
/** Used to show or hide a layer.

    @param pInstance @b IN The layer instance for the layer.
    @param show @b IN  true to show. false to hide.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

*/
extern tmErrorCode_t phStbVideoRenderer_Layer_ShowLayer(
    phStbVideoRenderer_Layer_t *pInstance,
    bool show);

/******************************************************************************/
/** Used to set the brightness of the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param brightness @b IN The brightness level (0-511, 255 default)

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    NAB TODO: Possibly supported by the Colour Space Matrix in Disp
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SetBrightness(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t brightness);

/******************************************************************************/
/** Used to get the brightness of the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param pBrightness @b OUT Pointer to storage for the current brightness level.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    NAB TODO: Possibly supported by the Colour Space Matrix in Disp
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetBrightness(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t *pBrightness);

/******************************************************************************/
/** Used to set the contrast of the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param contrast @b IN The contrast level (0-511, 255 default)

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    NAB TODO: Possibly supported by the Colour Space Matrix in Disp
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SetContrast(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t contrast);

/******************************************************************************/
/** Used to get the contrast of the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param pContrast @b OUT Pointer to storage for the current contrast level.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    NAB TODO: Possibly supported by the Colour Space Matrix in Disp
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetContrast(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t *pContrast);

/******************************************************************************/
/** Used to set the saturation of the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param saturation @b IN The saturation level (0-511, 255 default)

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    NAB TODO: Possibly supported by the Colour Space Matrix in Disp
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SetSaturation(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t saturation);

/******************************************************************************/
/** Used to get the saturation of the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param pSaturation @b OUT Pointer to storage for the current Saturation level.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    NAB TODO: Possibly supported by the Colour Space Matrix in Disp
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetSaturation(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t *pSaturation);

/******************************************************************************/
/** Used to set the hue value of the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param hue @b IN The hue level (0-255)

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    NAB TODO: Possibly supported by the Colour Space Matrix in Disp
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SetHue(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t hue);

/******************************************************************************/
/** Used to get the current hue value of the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param pHue @b OUT Pointer to storage for the current Hue setting.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    NAB TODO: Possibly supported by the Colour Space Matrix in Disp
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetHue(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t *pHue);

/******************************************************************************/
/** Used to set the value of white for this layer.

    @param pInstance @b IN The layer instance for the layer.
    @param red   @b IN The Red Value of white. (180 - 255 setting)
    @param green @b IN The Green Value of white. (180 - 255 setting)
    @param blue  @b IN The Blue Value of white. (180 - 255 setting)

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    NAB TODO: Possibly supported by the Colour Space Matrix in Disp
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SetWhitePoint(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t red,
    uint32_t green,
    uint32_t blue);

/******************************************************************************/
/** Used to get the whitepoint setting for this layer.

    @param pInstance @b IN The layer instance for the layer.
    @param pRed   @b OUT Pointer to storage for the current Red Value of white.
    @param pGreen @b OUT Pointer to storage for the Green Value of white.
    @param pBlue  @b OUT Pointer to storage for the Blue Value of white.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    NAB TODO: Possibly supported by the Colour Space Matrix in Disp
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetWhitePoint(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t *pRed,
    uint32_t *pGreen,
    uint32_t *pBlue);

/******************************************************************************/
/** Sets the source rectangle for use by the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param ulx @b IN  The Upper Left X Co-ordinate (inclusive).
    @param uly @b IN  The Upper Left Y Co-ordinate (inclusive).
    @param lrx @b IN  The Lower Right X Co-ordinate (exclusive).
    @param lry @b IN  The Lower Right Y Co-ordinate (exclusive).
    @param immediate @b IN true to set immediately. false to wait for vsync.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    @note Rectangles on this API work as follows. (ulx,uly) is the top left hand
    corner, and is included in the area. (lrx,lry) is the bottom right hand corner,
    and is not included in the area. This means that (width = lrx - ulx) and
    (height = lry - uly).

    @note PH_STBVIDEORENDERER_ERR_INVALID_RECT is returned in the following circumstances
          the chosen rectangle settings are not allowed:
          This is when the width of the rectangle i.e (lrx - ulx) < 64 pixels (PH_STBVIDEORENDERER_LAYER_MIN_RECT_SIZE),
          or when the height of the rectangle i.e (lry - uly) < 64 pixels (PH_STBVIDEORENDERER_LAYER_MIN_RECT_SIZE).
          It is also when any of the 4 values (ulx, uly, lrx, lry) are not divisable by 2.

    @see PH_STBVIDEORENDERER_LAYER_MIN_RECT_SIZE
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SetSrcRectangle(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t ulx,
    uint32_t uly,
    uint32_t lrx,
    uint32_t lry,
    bool     immediate);

/******************************************************************************/
/** Gets the current source rectangle in use by the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param pUlx @b OUT  Pointer to storage for the Upper Left X Co-ordinate (inclusive).
    @param pUly @b OUT  Pointer to storage for the Upper Left Y Co-ordinate (inclusive).
    @param pLrx @b OUT  Pointer to storage for the Lower Right X Co-ordinate (exclusive).
    @param pLry @b OUT  Pointer to storage for the Lower Right Y Co-ordinate (exclusive).

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    @note Rectangles on this API work as follows. (ulx,uly) is the top left hand
    corner, and is included in the area. (lrx,lry) is the bottom right hand corner,
    and is not included in the area. This means that (width = lrx - ulx) and
    (height = lry - uly).
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetSrcRectangle(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t *pUlx,
    uint32_t *pUly,
    uint32_t *pLrx,
    uint32_t *pLry);

/******************************************************************************/
/** Sets the destination rectangle for the current layer

    @param pInstance @b IN The layer instance for the layer.
    @param ulx @b IN  The Upper Left X Co-ordinate (inclusive).
    @param uly @b IN  The Upper Left Y Co-ordinate (inclusive).
    @param lrx @b IN  The Lower Right X Co-ordinate (exclusive).
    @param lry @b IN  The Lower Right Y Co-ordinate (exclusive).

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    @note Rectangles on this API work as follows. (ulx,uly) is the top left hand
    corner, and is included in the area. (lrx,lry) is the bottom right hand corner,
    and is not included in the area. This means that (width = lrx - ulx) and
    (height = lry - uly).

    @note PH_STBVIDEORENDERER_ERR_INVALID_RECT is returned in the follwing circumstances
          This is when the width of the rectangle i.e (lrx - ulx) < 64 pixels (PH_STBVIDEORENDERER_LAYER_MIN_RECT_SIZE),
          or when the height of the rectangle i.e (lry - uly) < 64 pixels (PH_STBVIDEORENDERER_LAYER_MIN_RECT_SIZE).
          It is also when any of the 4 values (ulx, uly, lrx, lry) are not divisable by 2.

    @see PH_STBVIDEORENDERER_LAYER_MIN_RECT_SIZE
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SetDestRectangle(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t ulx,
    uint32_t uly,
    uint32_t lrx,
    uint32_t lry);

/******************************************************************************/
/** Gets the current destination rectangle for this layer.

    @param pInstance @b IN The layer instance for the layer.
    @param pUlx @b OUT  Pointer to storage for the Upper Left X Co-ordinate (inclusive).
    @param pUly @b OUT  Pointer to storage for the Upper Left Y Co-ordinate (inclusive).
    @param pLrx @b OUT  Pointer to storage for the Lower Right X Co-ordinate (exclusive).
    @param pLry @b OUT  Pointer to storage for the Lower Right Y Co-ordinate (exclusive).

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    @note Rectangles on this API work as follows. (ulx,uly) is the top left hand
    corner, and is included in the area. (lrx,lry) is the bottom right hand corner,
    and is not included in the area. This means that (width = lrx - ulx) and
    (height = lry - uly).
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetDestRectangle(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t *pUlx,
    uint32_t *pUly,
    uint32_t *pLrx,
    uint32_t *pLry);

/******************************************************************************/
/** Used to set the alpha level of the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param alphaLevel @b IN The alpha level to use (0-255).

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    @note An alpha level of 0 means transparent, and 255 is fully visible.

    NAB TODO: Alpha on Disp 1 is a static register.
    Alpha on Disp 2 uses the Alpha block in the Vmix, which allows a static value
    or a matrix containing per-pixel alpha values.
    Alpha on Graphic 1 & 2 is done by colour keying (DAVIC) or per-pixel alpha values (ARGB),
    and there is also a per-region "shift" setting.
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SetAlphaLevel(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t alphaLevel);

/******************************************************************************/
/** Used to get the current alpha level of the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param pAlpha @b OUT Pointer to storage for the current alpha level (0-255).

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    @note An alpha level of 0 means transparent, and 255 is fully visible.
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetAlphaLevel(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t *pAlpha);

/******************************************************************************/
/** Used to set the flicker filtering mode of the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param enable    @b IN Enable/Disable Flicker Filtering

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SetFlickerFiltering(
    phStbVideoRenderer_Layer_t *pInstance,
    bool enable);

/******************************************************************************/
/** Used to get the flicker filtering mode of the layer.

    @param pInstance @b IN  The layer instance for the layer.
    @param enabled   @b OUT Flicker Filtering enabled/disabled

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetFlickerFiltering(
    phStbVideoRenderer_Layer_t *pInstance,
    bool *enabled);

#if 0
// NAB TODO: PIXEL FORMATS NOT YET DEFINED
/******************************************************************************/
/** Used to get the current pixel format of the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param pPixelFormat @b OUT Pointer to storage for the current pixel format setting.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetPixelFormat(
    phStbVideoRenderer_Layer_t *pInstance,
    phStbVideoTypes_PixelFormat_t *pPixelFormat);

/******************************************************************************/
/** Sets the clock synchronisation information for the layer.

    @param pInstance @b IN The layer instance for the layer.
    @param pSyncInfo @b IN Pointer to the sync information structure.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    @note The syncWindow should have a negative low value and a positive
    high value.

    NAB TODO: We don't yet have a spec for the AV sync mechanism; it's being handled by Caen
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SetSyncInfo(
    phStbVideoRenderer_Layer_t *pInstance,
    phStbSyncInfo_t *pSyncInfo);
#endif

/******************************************************************************/
/** Find out if this layer has scaling support enabled.

    @param pInstance @b IN The layer instance for the layer.
    @param pScalingSupported @b OUT Pointer to indicate supported/not.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    NAB TODO: Disp & Graphics both do hor/vert scaling.
    Even cursor can be scaled, although we probably aren't using that
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_IsScalingSupported(
    phStbVideoRenderer_Layer_t *pInstance,
    bool *pScalingSupported);

/******************************************************************************/
/** Sets up a layers input connection in terms of the number of frame packets
    and their format. The number of frame packets can vary depending on use case
    e.g. trick modes. The format can vary between none, SD and HD.

    @param pInstance @b IN The layer instance for the layer.
    @param numPackets @b IN The number of input frame packets for the layer.
    @param format @b IN The format of the frame packets for the layer.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SetInput(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t numPackets,
    phStbVideoRenderer_Layer_InputFormat_t format);

/******************************************************************************/
/** Sets up a layer's frame buffer pointer. This is only relevant for OSD
    layers, which have their memory managed externally and provided via this
    call. Before a valid buffer pointer is provided, the layer will be disabled.
    In order to disable the layer, provide a NULL buffer pointer.

    @param pInstance @b IN The layer instance for the layer.
    @param stride    @b IN Stride of the memory buffer (in pixels).
    @param height    @b IN Height of the memory buffer.
    @param pBuffer   @b IN A pointer to the start of the frame buffer memory.
    @param gfxType   @b IN Type of OSD layer
    @param pClut     @b IN A pointer to the CLUT (if applicable)

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_SetBufferPointer(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t stride,
    uint32_t height,
    void *pBuffer,
    phStbVideoRenderer_GfxMode_t gfxType,
    phStbVideoRenderer_GfxClut_t *pClut);

/******************************************************************************/
/** Pauses the presentation of the given layer so that its display does not
    update. Incoming data is queued up and will be processed when the layer
    is unpaused i.e. no data is lost.

    @param pInstance @b IN The layer instance for the layer.
    @param pause @b IN  true to pause. false to unpause.

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    NAB TODO: Can't see that this can be implemented tbh. Very much a TSSA concept
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_Pause(
    phStbVideoRenderer_Layer_t *pInstance,
    bool pause);

/******************************************************************************/
/** Gets the current frame information.

    @param pInstance            @b IN The layer instance for the layer.
    @param pTimeCode            @b OUT Pointer to the frame's time code
    @param pPictureType         @b OUT Pointer to the frame's picture type
    @param pTemporalReference   @b OUT Pointer to the frame's temporal reference

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    @note What the returned parameters actually mean may vary with video format
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetCurrentFrameInfo(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t* pTimeCode,
    uint32_t* pPictureType,
    uint32_t* pTemporalReference);

/******************************************************************************/
/** Gets the current clock time for the clock that is driving this layer.

    @param pInstance            @b IN The layer instance for the layer.
    @param pTimeLo              @b OUT pointer to storage for the low part of clock time
    @param pTimeHigh            @b OUT pointer to storage for the high part of clock time

    @retval TM_OK           Completed Successfully.
    @retval AnotherValue    An error.

    @note You will need to combine pTimeLo and pTimeHigh to be a 64 bit number for the
          clock time.
*/
extern tmErrorCode_t phStbVideoRenderer_Layer_GetVideoClockTime(
    phStbVideoRenderer_Layer_t *pInstance,
    uint32_t* pTimeLo,
    uint32_t* pTimeHigh);

#if TMFL_OS_IS_LINUX
/******************************************************************************/
/**** Linux IOCTLs *****/

/* The base of phStbVideoRenderer ioctls - ASCII 'V' value (for Video) */
#define PHSTBVIDEORENDERER_IOCTL_BASE 'V'

/* Get the video src rectangle */
#define PHSTBVIDEORENDERER_IOCTL_GET_SRC_RECT _IOR(PHSTBVIDEORENDERER_IOCTL_BASE, 1, uint32_t*)

/* Set the video blanking */
#define PHSTBVIDEORENDERER_IOCTL_SET_BLANK _IOW(PHSTBVIDEORENDERER_IOCTL_BASE, 2, uint32_t)

/* Get the video memory pointers */
#define PHSTBVIDEORENDERER_IOCTL_GET_MEM_PTRS _IOR(PHSTBVIDEORENDERER_IOCTL_BASE, 3, uint32_t*)

#endif

/******************************************************************************/

#ifdef __cplusplus
}
#endif

#endif /* Do not add anything below this line */

