/*

  display_chipset_api.h

  Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). 

  All rights reserved.

  This program and the accompanying materials are made available 

  under the terms of the Eclipse Public License v1.0 which accompanies 

  this distribution, and is available at 

  http://www.eclipse.org/legal/epl-v10.html

  Initial Contributors:

  Nokia Corporation - initial contribution.

  Contributors:

*/

/**

  @mainpage

  @section intro_sec Introduction

  <p>This is the display chipset driver API document.</p>

  <p>This API hides HW differences from display (and other users) driver.

  API is not kept as binary compatible.</p>

  <p></p>

  <p>Multiclient:

  API is purposed for multiclient use. Same chipset driver should take care

  more than one client in same time. Common HW (bus) will be shared

  for two clients, that way that they cannot detect sharing.</p>

  <p></p>

  <p>Resource managing:

  Chipset driver is responsible to allocate needed power resources. Chipset driver

  should deallocate resources immediately when those are not needed. Display

  driver (top of chipset driver) does not need allocate any of power resources for

  chipset driver.</p>

  <p></p>

  <p>DVFS (Dynamic Voltage and Frequency Scaling):

  Chipset driver is responsible to allocate needed clock state and

  listening if clock will change. It is better if display driver does not

  listening (top of chipset driver) DVFS at all, for avoiding death locks.</p>

  <p></p>

  <p>Structs:

  Always when some of any struct is created, creator is responsible to fill it

  with zeroes, and should use sizeof() operator. </p>

  <p></p>

  <p>Identifier:

  Functions where is not IDENTIFIER given, and chipset driver still need to detect

  the client, it has to implement couple of methods for same function, to getting

  difference using different function pointer.

  <p></p>

  <p>Image processing stages:

  Image processing should happen in order (or output should look like this):

  [Source image] -> [Color space conversion] -> [InputScissor] -> [Mirror] ->

  [Rotate] -> [TargetArea(Scaling)] -> [Offset] -> [Blend] -> [Output]</p>

  <p></p>

*/

/** @file

Declaration of display chipset driver API

@publishedDeviceAbstraction

*/

#ifndef DISPLAY_CHIPSET_API_H

#define DISPLAY_CHIPSET_API_H

/*- Include Files  ----------------------------------------------------------*/

#include "display_chipset_os.h" /* OS specific header file, typedef etc. */

/*- Data Types --------------------------------------------------------------*/

/*- Enumerations ------------------------------------------------------------*/

/** Error codes */

typedef enum  

    {

    DISP_ERROR_NONE,                    /**< OK */

    DISP_ERROR_FATAL,                   /**< Restart needed. Fatal error. */

    DISP_ERROR_INVALID_PARAMETER,       /**< Given parameter is not ok */

    DISP_ERROR_BUS_TIMEOUT,             /**< Possible Hw jam */

    DISP_ERROR_INVALID_BUFFER_FORMAT,   /**< Unknown buffer format */

    DISP_ERROR_BUFFER_FORMAT_MISMATCH,  /**< when target device has different format than the input hal_buffer and Hw is not capable to perform conversion */

    DISP_ERROR_OUT_OF_MEMORY,           /**< Chipset driver operation is not made, because out of memory */

    DISP_ERROR_NO_DEVICE,               /**< Device not found */

    DISP_ERROR_INVALID_SIZE,            /**< Given size parameters are too small or too big */

    DISP_ERROR_HW_IS_BUSY,              /**< Operation is not allowed, because Hw is reserved for another use */

    DISP_ERROR_USER_IS_NOT_RECOGNISED,  /**< User is not detected (parameter: identifier), or initialisiation is not done */

    DISP_ERROR_CANNOT_CLONE,            /**< If clone combination is impossible. @see dispCloneOutput() */

    DISP_ERROR_NOT_SUPPORTED,           /**< Given operation is not supported by Hw */

    DISP_ERROR_NOT_IMPLEMENTED,         /**< Given operation is not supported by Sw */

    DISP_ERROR_INVALID_NAME,            /**< Invalid name */

    DISP_ERROR_ALREADY_EXISTS,          /**< E.g.: Set twice */

    DISP_ERROR_NOT_FOUND,               /**< Something missing */

    DISP_ERROR_ALIGNMENT,               /**< Data alignment error */

    DISP_ERROR_NOT_READY,               /**< Device is not ready for operation */

    DISP_ERROR_CANCELLED,               /**< Operation cancelled */

    DISP_ERROR_NO_CLOCK,                /**< Bad clock signal */

    DISP_ERROR_BLUE,                    /**< Blue color error */

    DISP_ERROR_GREEN,                   /**< Green color error */

    DISP_ERROR_RED,                     /**< Red color error */

    DISP_ERROR_NOT_IDENTIFIED,          /**< Cannot identify HW */

    DISP_ERROR_TE_MISSED,               /**< Tearing Effect line is not detected */

    DISP_ERROR_RESET,                   /**< Reset line error */

    DISP_ERROR_DATA_LINES,              /**< Data lines error */

    DISP_ERROR_AUDIO,                   /**< HDMI audio error */

    DISP_ERROR_CEC,                     /**< CEC error */

    DISP_ERROR_DDC,                     /**< DDC error */

    DISP_ERROR_HPD,                     /**< Hot Plug Detection */

    DISP_ERROR_NO_POWER,                /**< Not powered */

    DISP_ERROR_NACK,                    /**< Not acknowledged */

    DISP_ERROR_CRC,                     /**< CRC error */

    } DISPE_ERROR;

/** Rotation and flipping */

typedef enum

    {

    DISP_ROTATION_INVALID           = 0x0000,    /**< Initialisation value, don't use */

    DISP_ROTATION_0                 = ( 1 << 0 ),/**< No rotation      */

    DISP_ROTATION_90                = ( 1 << 1 ),/**< 90 degree        */

    DISP_ROTATION_180               = ( 1 << 2 ),/**< 180 degree       */

    DISP_ROTATION_270               = ( 1 << 3 ),/**< 270 degree       */

    DISP_ROTATION_MIRROR_VERTICAL   = ( 1 << 4 ),/**< Upside down/flip */

    DISP_ROTATION_MIRROR_HORIZONTAL = ( 1 << 5 ),/**< Mirrored         */

    } DISPE_ROTATION;

/** Color format */

const uint32 KLittleEndian = 0x0;

const uint32 KBigEndian    = 0x1;

typedef enum

    {

    DISP_COLOR_FORMAT_INVALID      = 0,                          /**< Initialisation value, don't use */

    DISP_COLOR_FORMAT_XRGB8888_LE  = ( 1 << 1 )  | KLittleEndian,

    DISP_COLOR_FORMAT_XRGB8888_BE  = ( 1 << 1 )  | KBigEndian,

    DISP_COLOR_FORMAT_ARGB8888_LE  = ( 1 << 2 )  | KLittleEndian,

    DISP_COLOR_FORMAT_ARGB8888_BE  = ( 1 << 2 )  | KBigEndian,

    DISP_COLOR_FORMAT_ARGB8888P_LE = ( 1 << 3 )  | KLittleEndian, /** Pre-multiplied */

    DISP_COLOR_FORMAT_ARGB8888P_BE = ( 1 << 3 )  | KBigEndian,

    DISP_COLOR_FORMAT_RGB888_LE    = ( 1 << 4 )  | KLittleEndian,

    DISP_COLOR_FORMAT_RGB888_BE    = ( 1 << 4 )  | KBigEndian,

    DISP_COLOR_FORMAT_RGB565_LE    = ( 1 << 5 )  | KLittleEndian,

    DISP_COLOR_FORMAT_RGB565_BE    = ( 1 << 5 )  | KBigEndian,

    DISP_COLOR_FORMAT_ARGB1555_LE  = ( 1 << 6 )  | KLittleEndian,

    DISP_COLOR_FORMAT_ARGB1555_BE  = ( 1 << 6 )  | KBigEndian,

    DISP_COLOR_FORMAT_ARGB1555P_LE = ( 1 << 7 )  | KLittleEndian, /** Pre-multiplied */

    DISP_COLOR_FORMAT_ARGB1555P_BE = ( 1 << 7 )  | KBigEndian,

    DISP_COLOR_FORMAT_ARGB4444_LE  = ( 1 << 8 )  | KLittleEndian,

    DISP_COLOR_FORMAT_ARGB4444_BE  = ( 1 << 8 )  | KBigEndian,

    DISP_COLOR_FORMAT_ARGB4444P_LE = ( 1 << 9 )  | KLittleEndian, /** Pre-multiplied */

    DISP_COLOR_FORMAT_ARGB4444P_BE = ( 1 << 9 )  | KBigEndian,

    DISP_COLOR_FORMAT_YCBCR422_LE  = ( 1 << 10 ) | KLittleEndian,

    DISP_COLOR_FORMAT_YCBCR422_BE  = ( 1 << 10 ) | KBigEndian,

    DISP_COLOR_FORMAT_YCBCR420_LE  = ( 1 << 11 ) | KLittleEndian,

    DISP_COLOR_FORMAT_YCBCR420_BE  = ( 1 << 11 ) | KBigEndian,

    DISP_COLOR_FORMAT_PLATFORM     = ( 1 << 12 ),                /**< Non standard, platform specific format */

    } DISPE_COLOR_FORMAT;

/** YCbCr standard bit mask */

typedef enum

    {

    DISP_COLOR_FORMAT_YCBCR_INVALID  = 0x0000,    /**< Can be set when RGB */

    DISP_COLOR_FORMAT_FULL_RANGE     = ( 1 << 0 ),/**< Full range 0-255 */

    DISP_COLOR_FORMAT_LIMITED_RANGE  = ( 1 << 1 ),/**< Limited range 16-235 */

    } DISPE_COLOR_YCBCR_BIT_MASK;

/** Colorspace - API supports one case-by-case fixed conversion matrix (FIXED) for one most used conversion */

typedef enum

    {

    DISP_COLOR_SPACE_NONE              = 0x0000,     /**< Initialisation value, don't use */

    DISP_COLOR_SPACE_LINEAR_RGB        = ( 1 << 0 ), /**< Linear color space */

    DISP_COLOR_SPACE_STANDARD_RGB      = ( 1 << 1 ), /**< sRGB, Red[0.6400, 0.3300] Green[0.3000, 0.6000] Blue[0.1500, 0.0600] White[0.3127,0.3290] */

    DISP_COLOR_FIXED_DISPLAY_CS_LINEAR = ( 1 << 2 ), /**< Fixed display color space - Buffer pixels are linearised RGB for FIXED */

    DISP_COLOR_FIXED_DISPLAY_CS        = ( 1 << 3 ), /**< Fixed display color space */

    DISP_COLOR_COORDINATES             = ( 1 << 4 ), /**< With this, Chipset driver does the conversion, according to input and output coordinates */

    DISP_COLOR_MATRIX_CONV             = ( 1 << 5 ), /**< Free 3x3 matrix conversion. @see DISPS_COLOR_SPACE_CONV_MATRIX */

    } DISPE_COLOR_SPACE;

/** Scaling */

typedef enum

    {

    DISP_SCALING_NO                 = 0x0000,    /**< No HW support for scaling */

    DISP_SCALING_NEAREST_NEIGHBOUR  = ( 1 << 0 ),/**< Style: Plain pixel copy */

    DISP_SCALING_BILINEAR_OR_BEST   = ( 1 << 1 ),/**< Style: Bilinear or better*/

    } DISPE_SCALING;

/** Display Interface Types */

const uint32 KMeSSIBus         = 0x1; /**< MIPI DBI-2 type B */

const uint32 KLoSSIBus         = 0x2; /**< MIPI DBI-2 type C option 1 */

const uint32 KViSSIBus         = 0x3; /**< MIPI DPI-2 */

const uint32 KCDPBus           = 0x4; /**< CDP (HiSSI-V)=No corresponding MIPI standard. LoSSI works as control bus. */

const uint32 KDSIVideoBus      = 0x5; /**< DSI (HiSSI-M)=MIPI DSI1.1, Videobus */

const uint32 KDSICmdBus        = 0x6; /**< DSI (HiSSI-M)=MIPI DSI1.1, Commandbus */

const uint32 KOffscreenDisplay = 0x7; /**< Offscreen display, for possible USB, WLAN, etc. purpose */

const uint32 KCvbsBus          = 0x8;

const uint32 KHdmiBus          = 0x9;

const uint32 KDdcBus           = 0xA;

const uint32 KCecBus           = 0xB;

const uint32 KInterfaceNumberShift = 5;

typedef enum

    {

    DISP_BUS_NONE   = 0,                                              /**< Initialisation value */

    DISP_BUS_MESSI0 = (  0 << KInterfaceNumberShift ) | KMeSSIBus,    /**< MeSSI bus ID:0 */

    DISP_BUS_MESSI1 = (  1 << KInterfaceNumberShift ) | KMeSSIBus,

    DISP_BUS_MESSI2 = (  2 << KInterfaceNumberShift ) | KMeSSIBus,

    DISP_BUS_MESSI3 = (  3 << KInterfaceNumberShift ) | KMeSSIBus,

    DISP_BUS_MESSI4 = (  4 << KInterfaceNumberShift ) | KMeSSIBus,

    DISP_BUS_LOSSI0 = (  0 << KInterfaceNumberShift ) | KLoSSIBus,    /**< LoSSI bus ID:0 */

    DISP_BUS_LOSSI1 = (  1 << KInterfaceNumberShift ) | KLoSSIBus,

    DISP_BUS_LOSSI2 = (  2 << KInterfaceNumberShift ) | KLoSSIBus,

    DISP_BUS_LOSSI3 = (  3 << KInterfaceNumberShift ) | KLoSSIBus,

    DISP_BUS_LOSSI4 = (  4 << KInterfaceNumberShift ) | KLoSSIBus,

    DISP_BUS_VISSI0 = (  0 << KInterfaceNumberShift ) | KViSSIBus,    /**< ViSSI ID:0 */

    DISP_BUS_VISSI1 = (  1 << KInterfaceNumberShift ) | KViSSIBus,

    DISP_BUS_VISSI2 = (  2 << KInterfaceNumberShift ) | KViSSIBus,

    DISP_BUS_VISSI3 = (  3 << KInterfaceNumberShift ) | KViSSIBus,

    DISP_BUS_VISSI4 = (  4 << KInterfaceNumberShift ) | KViSSIBus,

    DISP_BUS_CDP0   = (  0 << KInterfaceNumberShift ) | KCDPBus,      /**< CDP ID:0 */

    DISP_BUS_CDP1   = (  1 << KInterfaceNumberShift ) | KCDPBus,

    DISP_BUS_CDP2   = (  2 << KInterfaceNumberShift ) | KCDPBus,

    DISP_BUS_CDP3   = (  3 << KInterfaceNumberShift ) | KCDPBus,

    DISP_BUS_CDP4   = (  4 << KInterfaceNumberShift ) | KCDPBus,

    DISP_BUS_DSIV0  = (  0 << KInterfaceNumberShift ) | KDSIVideoBus, /**< HiSSI-M ID:0. ID maps to Virtual Channel */

    DISP_BUS_DSIV1  = (  1 << KInterfaceNumberShift ) | KDSIVideoBus,

    DISP_BUS_DSIV2  = (  2 << KInterfaceNumberShift ) | KDSIVideoBus,

    DISP_BUS_DSIV3  = (  3 << KInterfaceNumberShift ) | KDSIVideoBus,

    DISP_BUS_DSIV4  = (  4 << KInterfaceNumberShift ) | KDSIVideoBus, /**< ID:0 in second physical layer */

    DISP_BUS_DSIV5  = (  5 << KInterfaceNumberShift ) | KDSIVideoBus,

    DISP_BUS_DSIV6  = (  6 << KInterfaceNumberShift ) | KDSIVideoBus,

    DISP_BUS_DSIV7  = (  7 << KInterfaceNumberShift ) | KDSIVideoBus,

    DISP_BUS_DSIV8  = (  8 << KInterfaceNumberShift ) | KDSIVideoBus, /**< ID:0 in third physical layer */

    DISP_BUS_DSIV9  = (  9 << KInterfaceNumberShift ) | KDSIVideoBus,

    DISP_BUS_DSIV10 = ( 10 << KInterfaceNumberShift ) | KDSIVideoBus,

    DISP_BUS_DSIV11 = ( 11 << KInterfaceNumberShift ) | KDSIVideoBus,

    DISP_BUS_DSIC0  = (  0 << KInterfaceNumberShift ) | KDSICmdBus,   /**< HiSSI-M ID:0. ID maps to Virtual Channel */

    DISP_BUS_DSIC1  = (  1 << KInterfaceNumberShift ) | KDSICmdBus,

    DISP_BUS_DSIC2  = (  2 << KInterfaceNumberShift ) | KDSICmdBus,

    DISP_BUS_DSIC3  = (  3 << KInterfaceNumberShift ) | KDSICmdBus,

    DISP_BUS_DSIC4  = (  4 << KInterfaceNumberShift ) | KDSICmdBus,   /**< ID:0 in second physical layer */

    DISP_BUS_DSIC5  = (  5 << KInterfaceNumberShift ) | KDSICmdBus,

    DISP_BUS_DSIC6  = (  6 << KInterfaceNumberShift ) | KDSICmdBus,

    DISP_BUS_DSIC7  = (  7 << KInterfaceNumberShift ) | KDSICmdBus,

    DISP_BUS_DSIC8  = (  8 << KInterfaceNumberShift ) | KDSICmdBus,   /**< ID:0 in third physical layer */

    DISP_BUS_DSIC9  = (  9 << KInterfaceNumberShift ) | KDSICmdBus,

    DISP_BUS_DSIC10 = ( 10 << KInterfaceNumberShift ) | KDSICmdBus,

    DISP_BUS_DSIC11 = ( 11 << KInterfaceNumberShift ) | KDSICmdBus,

    DISP_BUS_OFFSCR = KOffscreenDisplay,                              /**< Offscreen display */

    DISP_BUS_CVBS   = KCvbsBus,                                       /**< Composite Tv-out */

    DISP_BUS_HDMI   = KHdmiBus,                                       /**< Hdmi Tv-out */

    DISP_BUS_DDC    = KDdcBus,                                        /**< DDC bus (HDMI and DVI) */

    DISP_BUS_CEC    = KCecBus,                                        /**< CEC bus (HDMI) */

    } DISPE_BUS;

/** Transfer mode */

typedef enum

    {

    DISP_BUS_0BIT  = 0x0000,    /**< Initialisation value, don't use */

    DISP_BUS_1BIT  = ( 1 << 0 ),/**< 1bit width bus, bidirectional LoSSI */

    DISP_BUS_2BIT  = ( 1 << 1 ),/**< LoSSI with separate read and write signals */

    DISP_BUS_3BIT  = ( 1 << 2 ),/**< E.g. DSI 3 lanes */

    DISP_BUS_4BIT  = ( 1 << 3 ),/**< E.g. DSI 4 lanes */

    DISP_BUS_8BIT  = ( 1 << 4 ),/**< E.g. MeSSI-8 */

    DISP_BUS_12BIT = ( 1 << 5 ),

    DISP_BUS_16BIT = ( 1 << 6 ),

    DISP_BUS_18BIT = ( 1 << 7 ),

    DISP_BUS_24BIT = ( 1 << 8 ),

    DISP_BUS_32BIT = ( 1 << 9 ),

    } DISPE_BUS_WIDTH;

/** Power control */

typedef enum

    {

    DISP_PWR_MODE_INVALID           = 0x0000,   /**< Initialisation value, don't use */

    DISP_PWR_MODE_ANALOG_POWER_ON   = 0x0011,   /**< External analogue voltages */

    DISP_PWR_MODE_ANALOG_POWER_OFF  = 0x0010,

    DISP_PWR_MODE_DIGITAL_POWER_ON  = 0x0021,   /**< External digital voltages */

    DISP_PWR_MODE_DIGITAL_POWER_OFF = 0x0020,

    DISP_PWR_MODE_RESET_ACTIVE      = 0x0041,   /**< Activate external reset signal. With DSI, RAR will be listened. */

    DISP_PWR_MODE_RESET_INACTIVE    = 0x0040,

    DISP_PWR_MODE_DISPLAY_ON        = 0x0081,   /**< Pixel clock for memoryless displays (ViSSI/HiSSI). LP/HS when DSI. */

    DISP_PWR_MODE_DISPLAY_OFF       = 0x0080,   /**< Ultra Low Power State (ULPS) mode when DSI */

    } DISPE_PWR_MODE;

/** Driver messages - @see dispDriverMessage */

typedef enum

    {

    DISP_MSG_PING      = 0x00000000,  /**< Ping for all drivers. All drivers forwards this msg and

                                           gives callback. Doesn't matter what is the 'receiver'-parameter. */

    DISP_MSG_SELFTEST  = 0x00000001,  /**< Selftest */

    DISP_MSG_PRODTEST  = 0x00000002,  /**< Production test */

    DISP_MSG_LAST      = 0xFFFFFFFF,  /**< Not in use */

    } DISPE_DRV_MSG;

/** Colorkey handling */

typedef enum

    {

    DISP_COLORKEYMODE_NONE       = 0x0000,      /**< No colorkey */

    DISP_COLORKEYMODE_SINGLE_KEY = ( 1 << 0 ),  /**< One color is colorkey (simplest) */

    DISP_COLORKEYMODE_KEY_MASK   = ( 1 << 1 ),  /**< Colorkey mask. If (pixel_color & mask) -> transparent pixel */

    DISP_COLORKEYMODE_ALPHA      = ( 1 << 2 ),  /**< To utilize alphachannel of source buffer for transparency, 

                                                     works with followings as ARGB : DISP_COLOR_FORMAT_ARGB8888, DISP_COLOR_FORMAT_ARGB1555 */

    } DISPE_COLORKEYMODE;

/** Tearing synchronisation type */

typedef enum

    {

    DISP_TE_SYNC_NO              = 0x0000,    /**< No HW support for tearing synchronization */

    DISP_TE_SYNC_VS_RAISING_EDGE = ( 1 << 0 ),/**< Vertical synchronization when raising edge */

    DISP_TE_SYNC_VS_FALLING_EDGE = ( 1 << 1 ),/**< Vertical synchronization when falling edge */

    DISP_TE_SYNC_HS_VS           = ( 1 << 2 ),/**< Horisontal and vertical tearing synchronization */

    DISP_TE_SYNC_VS_BUS_TRIGGER  = ( 1 << 3 ),/**< In DSI mode only (TEE) */

    } DISPE_TE_SYNC;

/** Advanced feature bit masks - Used for capability query */

typedef enum

    {

    DISP_FEATURE_NONE        = 0x0000,     /**< Initialisation value */

    DISP_FEATURE_SCALING     = ( 1 << 0 ), /**< Scaling */

    DISP_FEATURE_ALL_CASES   = ( 1 << 1 ), /**< No matter what is the used feature */

    DISP_FEATURE_ROTATION    = ( 1 << 2 ), /**< 90, 180 or 270 rotation */

    DISP_FEATURE_OVERLAY     = ( 1 << 3 ), /**< Overlay without colorkey and alpha */

    DISP_FEATURE_COLOR_KEY   = ( 1 << 4 ), /**< Overlay with colorkey */

    DISP_FEATURE_ALPHA_BLEND = ( 1 << 5 ), /**< Overlay with alpha */

    DISP_FEATURE_YCBCR       = ( 1 << 6 ), /**< YCbCr support */

    } DISPE_FEATURE;

/** Buffer's cache and MMU settings - Write buffers to be always enabled - Chipset driver is responsible to syncronise caches */

typedef enum

    {

    DISP_CACHE_NOTHING                = 0x0000,     /**< Only writebuffers */

    DISP_CACHE_WRITE_THROUGH          = ( 1 << 0 ), /**< Write through caches (writes to cache (if hit) and to memory) */

    DISP_CACHE_WRITE_ALLOCATION_L1    = ( 1 << 1 ), /**< Cache level 1 -line will be allocated for write access */

    DISP_CACHE_WRITE_ALLOCATION_L2    = ( 1 << 2 ), /**< Cache level 2 -line will be allocated for write access */

    DISP_CACHE_READ_ALLOCATION_L1     = ( 1 << 3 ), /**< Cache level 1 -line will be allocated for read access */

    DISP_CACHE_READ_ALLOCATION_L2     = ( 1 << 4 ), /**< Cache level 2 -line will be allocated for read access */

    DISP_CACHE_USER_READ_PRIVILEGE    = ( 1 << 5 ), /**< User code (user mode) have read accesses to buffer */

    DISP_CACHE_USER_WRITE_PRIVILEGE   = ( 1 << 6 ), /**< User code (user mode) have write accesses to buffer */

    DISP_CACHE_KERNEL_READ_PRIVILEGE  = ( 1 << 7 ), /**< Kernel code (supervisor undefined mode) have read accesses to buffer */

    DISP_CACHE_KERNEL_WRITE_PRIVILEGE = ( 1 << 8 ), /**< Kernel code (supervisor undefined mode) have write accesses to buffer */

    DISP_CACHE_ARM_ACCESSIBLE         = ( 1 << 9 ), /**< To be always defined if ARM can see the buffer. Otherwise can be allocated only for HW. */

    } DISPE_CACHE_SETTINGS;

/*- Data Structs ------------------------------------------------------------*/

/** Color Space Converter 3x3 matrix. To be defined if DISP_COLOR_MATRIX_CONV is used.

    Output conversion formula:

    Red Out   = (red[0]   * Rin) + (red[1]   * Gin) + (red[2]   * Bin) + red[3]

    Green Out = (green[0] * Rin) + (green[1] * Gin) + (green[2] * Bin) + green[3]

    Blue Out  = (blue[0]  * Rin) + (blue[1]  * Gin) + (blue[2]  * Bin) + blue[3] */

typedef struct

    {

    /** Fixed point position. E.g: value = ( red.cell1 >> fixedPoint ). E.g: fixedPoint=2 -> b0.00 */

    uint8 fixedPoint;

    /** Conversion matrixes per color component */

    int16 red[ 4 ];

    int16 green[ 4 ];

    int16 blue[ 4 ];

    } DISPS_COLOR_SPACE_CONV_MATRIX;

/** CIE 1931 color space coordinates. To be defined if DISP_COLOR_COORDINATES is used.

    When chipset driver knows source and destination coordinates, it can operate

    conversion from source to destination. Fixed point is 10th bit.

    E.g. If redX=625, it should be divided by 1024 (2^10) for getting real value 0.61035... */

typedef struct

    {

    /** Red chromaticity coordinates */

    uint16 redX;

    uint16 redY;

    /** Green chromaticity coordinates */

    uint16 greenX;

    uint16 greenY;

    /** Blue chromaticity coordinates */

    uint16 blueX;

    uint16 blueY;

    /** White chromaticity coordinates */

    uint16 whiteX;

    uint16 whiteY;

    } DISPS_COLOR_COORDINATES;

/** Rectangle */

typedef struct

    {

    /** Begin line (first line is 0) */

    uint16 startRow;

    /** Begin column (first column is 0) */

    uint16 startColumn;

    /** Rectangle height in pixels */

    uint16 rows;

    /** Rectangle width in pixels */

    uint16 columns;

    } DISPS_RECTANGLE;

/** Source buffer dimensions and format */

typedef struct

    {

    /** Local memory linear address */

    void* bufferLinearAddress;

    /** Local memory physical address */

    uint32 bufferPhysicalAddress;

    /** Can be zero. Required if not-local memory, then addresses can be NULL */

    uint32 bufferId;

    /** Physically linear */

    bool8 physicallyLinear;

    /** Cache/MMU features - bit mask */

    DISPE_CACHE_SETTINGS caches;

    /** Features what to be used for this buffer - This is like usage-hint for chipset driver, and can be ignored */

    DISPE_FEATURE bufferUseCases;

    /** Offset from bufferPhysicalAddress to Y-components (needed if planar, otherwise can be set 0) */

    uint32 offsetToY;

    /** Offset from bufferPhysicalAddress to Cb-components (needed if planar, otherwise can be set 0) */

    uint32 offsetToCb;

    /** Offset from bufferPhysicalAddress to Cr-components (needed if planar, otherwise can be set 0) */

    uint32 offsetToCr;

    /** Source buffer pixel format */

    DISPE_COLOR_FORMAT pixelFormat;

    /** Source buffer color space (normally = DISP_COLOR_SPACE_STANDARD_RGB) */

    DISPE_COLOR_SPACE sourceColorSpace;

    /** Source buffer color space (free) to be defined if sourceColorSpace=DISP_COLOR_COORDINATES */

    DISPS_COLOR_COORDINATES sourceColorCoordinates;

    /** Used if API user wants to use free conversion table, to be defined if sourceColorSpace=DISP_COLOR_MATRIX_CONV */

    DISPS_COLOR_SPACE_CONV_MATRIX colorSpaceConversion;

    /** Required if YCbCr format used */

    DISPE_COLOR_YCBCR_BIT_MASK yCbCrBitMask;

    /** Buffer width in pixels */

    uint32 width;

    /** Buffer height in pixels */

    uint32 height;

    /** One line in bytes. With 420 planar, this tells one line Y-components stride. */

    uint32 stride;

    } DISPS_BUFFER;

/** Colorkey - Makes hole to layer */

typedef struct

    {

    /** Only one colorkeymode can be defined */

    DISPE_COLORKEYMODE mode;

    /** If DISP_COLORKEYMODE_SINGLE_KEY -> Defines transparency key when needed. Planar not supported.

        If DISP_COLORKEYMODE_KEY_MASK -> if (pixel_color & colorkey) -> transparent pixel. Then colorkey defines maskColor. */

    uint32 colorkey;

    } DISPS_COLORKEY;

/** Layer - one visible layer information */

typedef struct

    {

    /** True when this layer is enabled */

    bool8 enabled;

    /** True if forces transfer to display. Forcing means that chipset drv logic cannot do any own decisions

        (optimising/buffer changes/buffer manipulation) for the transfers. When this is true, buffer content must be

        visible on display panel after transfer. Normally can be false. */

    bool8 forceView;

    /** Source buffer struct */

    DISPS_BUFFER sourceBuffer;

    /** Input crop. Max size < sourceBuffer.width & height. */

    DISPS_RECTANGLE inputScissor;

    /** Target area coordinates. if source area is different size than target up/downscaling will need to be 

        performed  by HW. Return Error if scaling requested but no HW capability. */

    DISPS_RECTANGLE targetArea;

    /* If inputScissor!=targetArea sizes mismatch, then scaling method need to be defined here */

    DISPE_SCALING scalingMethod;

    /** Layer rotation information */

    DISPE_ROTATION rotate;

    /** Colorkey struct which is used in this buffer */

    DISPS_COLORKEY colorkey;

    /** Brightness value on screen, [-100,100]%, may be ignored by the driver.

        If chipset driver can control only one brightness (not for each layer),

        then first layer settings are used. */

    int16 brightness;

    /** Contrast value on screen, [-100,100]%

        If chipset driver can control only one contrast (not for each layer),

        then first layer settings are used. */

    int16 contrast;

    /** Gamma value on screen, e.g.: 1.00=100, 2.20=220.

        If chipset driver can control only one gamma (not for each layer),

        then DISPS_FINAL_VIEW::topLayer settings are used.

        Formula: output_signal = intensity^( 1 / gamma )

        In the C++ language this can be represented as follows:

         output_signal = pow( double( intensity ), double( 1.0 ) / ( double( gamma ) / 100 ) );

        Gamma-correction lookup table can be constructed like this:

         int32 lut[ 256 ];

         for ( int32 intensity = 0; intensity < 256; intensity++ )

             lut[ i ] = pow( double( intensity ), double( 1.0 ) / ( double( gamma ) / 100 ) );

        Loading this table into the hardware lookup table at the output side of

        framebuffer will cause RGB intensity values with integer components

        between 0 and 255 to be gamma-corrected by the hardware as if by the following code:

         red_signal   = lut[ r ];

         green_signal = lut[ g ];

         blue_signal  = lut[ b ]; */

    uint16 gamma;

    /** True when dithering is enabled (if HW does not support, then ignore this without error) */

    bool8 enableDithering;

    /** Per layer alpha if supported, 0x00-0xFF (if HW does not support, then ignore this without error) */

    uint8 perLayerAlphaValue;

    } DISPS_LAYER;

/**

Final view - composed view information

@code

__________________________ __________________________ __________________________

|                        | |                        | |                        |

|    DISPS_COLORKEY (1)  | |   DISPS_RECTANGLE (2)  | |     DISPS_BUFFER (1)   |

|                        | |                        | |                        |

¯¯¯¯¯¯¯¯¯¯¯¯|¯¯¯¯¯¯¯¯¯¯¯¯¯ ¯¯¯¯¯¯¯¯¯¯¯¯|¯¯¯¯¯¯¯¯¯¯¯¯¯ ¯¯¯¯¯¯¯¯¯¯¯¯|¯¯¯¯¯¯¯¯¯¯¯¯¯

            `--------------------------|--------------------------´

                           ____________|_____________

                           |                        |

                           |      DISPS_LAYER (5)   |

                           |                        |