//-----------------------------------------------------------------------------
// Copyright (c) 2006-2009 Intel Corporation
//
// DISTRIBUTABLE AS SAMPLE SOURCE SOFTWARE
//
// This Distributable As Sample Source Software is subject to the terms and
// conditions of the Intel Software License Agreement provided with the Intel(R)
// Media Processor Software Development Kit.
//-----------------------------------------------------------------------------

#ifndef _GDL_H_
#define _GDL_H_

#include "gdl_types.h"
#include "gdl_pd.h"

#if defined(__cplusplus)
extern "C" {
#endif

/*------------------------------------------------------------------------------
 * IMPORTANT!
 *
 * Change of a structure/type or a function prototype requires rolling of an
 * appropriate version number. For more information see gdl_version.h
 *----------------------------------------------------------------------------*/

/**@mainpage
 * This document is applicable to the Intel Media Processor CE 3100 and the
 * Sodaville processor. In this document, both processors are referred to as
 * the Intel CE Media Processors. When functional differences occur,
 * applicability to platform/silicon will be delineated.
 */

/**@defgroup general        General */

/**@defgroup disp_mode      Display Mode*/

/**@defgroup plane_management Plane Management

  A plane is a unit of hardware that can supply pixel data to be composited
  with the pixel data of other planes for output to the display.  Different
  kinds of planes have different capabilities.  The Intel CE Media Processors
  contain two kinds of planes:
  - Universal Pixel Planes (UPPs)
  - Indexed/Alpha Planes (IAPs)

  The Plane Management API provides a generic way to configure a plane and
  populate it with pixel data.  The main components of the API are:

  - <b>A predefined set of plane attributes.</b> Attributes are specified as
    name/value pairs. The enumeration #gdl_plane_attr_t defines the attribute
    names. The documentation of this data type describes each attribute
    including:
    - the plane capability controlled by the attribute.
    - the data type of the attribute's value.
    - the range of valid values that can be assigned to the attribute.
    - the default value of the attribute.

  - <b>The ability to query a plane for its capabilities.</b> Each plane type
    may support a different subset of the defined attributes and different
    set of pixel formats.  gdl_plane_capabilities() returns a description of
    the attributes and pixel formats supported by a specified plane.

  - <b>A set of attribute query functions.</b> These functions return the
    current hardware setting of the specified attribute on the specified plane.
    The only difference between the functions is the data type returned.
    - gdl_plane_get_attr()
    - gdl_plane_get_int()
    - gdl_plane_get_uint()
    - gdl_plane_get_rect()

  - <b>A set of attribute configuration functions.</b> For each of the query
    functions there is a corresponding set function.  All attribute set
    function calls must be bracketed by calls to configuration begin/end
    functions.  The specified attributes values are "batched" and executed
    only when the end function is called.  Batching provides atomicity of
    configuration changes and avoids getting into invalid states when related
    attributes must be changed at the same time.  The sequence of calls made
    to configure a plane is as follows:
    - gdl_plane_config_begin()
    - one or more calls to:
          - gdl_plane_set_attr()
          - gdl_plane_set_int()
          - gdl_plane_set_uint()
          - gdl_plane_set_rect()
    - gdl_plane_config_end()

  - <b>A surface flip function.</b>  A surface is a memory buffer containing
    pixel information.  See @ref surface for more information.  The gdl_flip()
    function "flips" a surface onto a plane, making the pixels in that surface
    visible.

  @warning  Plane defaults (including if they are enabled or disabled) are
            set when the display driver is loaded, and when
            @ref gdl_plane_reset() and @ref gdl_plane_reset_all() are called.
            They are <b>not</b> set by @ref gdl_init().
 */

/**@defgroup surface        Surface Management

  A surface is a memory buffer containing pixel data.
 */

/**@defgroup disp_vbi       VBI and Polarity */

/**@defgroup disp_pd        Port Drivers */

/**@defgroup debug          Debug helpers

  The majority of the functions in this group dump the contents of data
  structures to stdout or return string representations (that can be used in
  messages) for the values of various GDL enumerations.
 */

#ifndef DOXYGEN_SKIP
#define GDL_API __attribute__ ((visibility ("default")))
#else
#define GDL_API " "
#endif

GDL_API gdl_ret_t
gdl_init(
    gdl_void * reserved0
    );
    /**< @ingroup general

    This routine initializes the session and initiates communication with
    the display driver server daemon.  Calls to any other GDL functions will
    fail until this call is made. It must be called once per process. All
    threads in a process are then able to use the GDL API.

    Subsequent calls to gdl_init() (without an intervening call to gdl_close())
    will return #GDL_SUCCESS and increment an internal reference count.

    @param [in] reserved0
    This parameter is reserved for future use and should be set to 0.

    @note   This routine does not restore plane or port driver defaults
            that may have been changed by a previously running GDL
            application.  Plane defaults can be restored by using
            @ref gdl_plane_reset() and @ref gdl_plane_reset_all().  No
            restoration functionality exists for port drivers.
    */

#ifndef DOXYGEN_SKIP /* DOXYGEN_SKIP only defined when docs are generated */
GDL_API gdl_ret_t _gdl_init(gdl_uint32 version);
#define gdl_init(reserved0) _gdl_init((GDL_HEADER_VERSION_MAJOR << 16) \
                                      | GDL_HEADER_VERSION_MINOR)
#endif

GDL_API gdl_ret_t
gdl_close(
    void
    );
    /**< @ingroup general

    This function decrements the internal reference count that gdl_open()
    increments.  Once the reference count goes to zero, communication with the
    display driver server daemon is closed and the session is terminated.
    Subsequent calls to the GDL API from within the same process will fail until
    gdl_init() is called again.

    The use of a reference account allows pairs of gdl_open()/gdl_close() calls
    to be used, for instance, in separate threads in the same process without
    interference.

    When the session is terminated, any unfreed surfaces that were allocated by
    the calling process are freed, and warnings are printed to the console. If
    a surface freed in this manner is currently being displayed, the plane it is
    displayed on is first disabled.  No other hardware settings are changed;
    applications launched subsequently will inherit the hardware configuration
    left behind by the closing process.
    */

GDL_API gdl_ret_t
gdl_get_driver_info(
    gdl_driver_info_t * driver_info
    );
    /**< @ingroup general

    This routine returns driver information to the caller.  This information
    can be used to verify the version of the gdl driver.

    @param [out] driver_info
    This parameter is of type #gdl_driver_info_t.  This info contains the
    driver version as well as other info.
    */

GDL_API gdl_ret_t
gdl_closed_caption_source(
    gdl_plane_id_t plane_id
    );
    /**< @ingroup general

    This function allows specification of the video stream to be used as the
    source for closed caption data.

    The vbd_flip() function (of the VBD interface) allows the caller to flip a
    field/frame from a video stream onto a specified Universal Pixel Plane.
    Closed caption data associated with the frame is passed along in the same
    call.

    However, it is possible for multiple video streams to be displayed at the
    same time, on different planes.  The internal TV encoder(s) can only process
    one CC stream at a time -- intermixing streams will result in garbage being
    displayed for CC text.

    The plane ID passed to this function determines which CC stream will be
    passed along to the internal TV encoder(s).  CC data passed for streams
    flipped onto any other planes will be discarded.

    By default, the CC source is GDL_PLANE_ID_UNDEFINED, which causes *all* CC
    data passed to vbd_flip() to be ignored.

    @param [in]  plane_id
    The ID of the Universal Pixel Plane to which the currently selected CC
    stream will be directed.  If the value is GDL_PLANE_ID_UNDEFINED, all CC
    data passed via vbd_flip() calls will be ignored.
    */

GDL_API gdl_ret_t
gdl_get_display_info(
    gdl_display_id_t     display_id,
    gdl_display_info_t * display_info
    );
    /**< @ingroup disp_mode

    This routine returns the current display settings including resolution,
    refresh rate, and so on.

    @param [in] display_id
    The ID of the display whose settings should be retrieved.

    @param [out] display_info
    A pointer to a #gdl_display_info_t structure that will receive the current
    display settings.
    */

GDL_API gdl_ret_t
gdl_set_display_info(
    gdl_display_info_t * display_info
    );
    /**< @ingroup disp_mode

    This routine sets the display to the configuration specified by the
    display_info parameter.

    @param [in] display_info
    The desired display configuration.  The 'id' field of the structure
    indicates the display that is to be configured.
    */

GDL_API gdl_ret_t
gdl_check_tvmode(
    gdl_display_id_t id,
    gdl_tvmode_t *   mode
    );
    /**< @ingroup disp_mode

    Returns #GDL_SUCCESS if and only if the specified display mode is supported
    on all of the port drivers currently active on the specified display.

    @param [in] id
    Display of interest.

    @param [in] mode
    Mode of interest.
    */

GDL_API gdl_ret_t
gdl_get_port_tvmode_by_index(
    gdl_pd_id_t    id,
    gdl_uint32     index,
    gdl_tvmode_t * mode
    );
    /**< @ingroup disp_mode

    This routine can be used to enumerate the display modes supported by a
    given port driver.  The supported modes are indexed by 0-based consecutive
    integer values.  Calling this function with index==0 will return
    information about the first supported mode; calling it with index==1
    will return information about the second supported mode; and so on.

    The function returns GDL_SUCCESS as long as 'index' < N, where N is the
    number of modes supported by the port driver.

    @param [in] id
    Port driver of interest.

    @param [in] index
    Mode index.

    @param [out] mode
    Display mode information is returned here if the return value is
    GDL_SUCCESS; otherwise, the contents of this structure are meaningless.
    */

GDL_API gdl_ret_t
gdl_wait_for_vblank(
    gdl_polarity_t * polarity
    );
    /**< @ingroup disp_vbi

    This routine will block until the next Vertical Blanking Interval (VBI) has
    begun, as indicated by the VBlank signal.  Return value other than
    GDL_SUCCESS indicates that no VBI occurred during the expected time
    interval. This may indicate that PIPE A is not enabled.
    @b NOTE: The latency between VBI and return from this call can be affected
    by a system load. 

    @param [out] polarity
    If this argument is NULL it is ignored.  Otherwise, the polarity of the new
    active region is returned, as a value of type #gdl_polarity_t
    */

GDL_API gdl_ret_t
gdl_get_display_polarity(
    gdl_polarity_t * polarity
    );
    /**< @ingroup disp_vbi

    This routine will return immediately the current display polarity.

    @param [out] polarity
    The polarity is returned here.  See #gdl_polarity_t.
    */

GDL_API gdl_ret_t
gdl_alloc_surface(
    gdl_pixel_format_t   pixel_format,
    gdl_uint32           width,
    gdl_uint32           height,
    gdl_uint32           flags,
    gdl_surface_info_t * surface_info
    );
    /**< @ingroup surface

    This routine allocates a surface with the specified characteristics.  The
    driver will determine the required alignment and validate the requested
    surface attributes, and may alter them according to the device status.

    @param [in] pixel_format
    The pixel format of the surface.

    @param [in] width
    The width of the surface in pixels.

    @param [in] height
    The height of the surface in pixels.

    @param [in] flags
    Any number of flags of type #gdl_surface_flag_t OR'd together that
    describe the type of surface and the intended usage.

    @param [out] surface_info
    This parameter is returned to the caller and contains information about the
    surface that was just created.

    @b NOTE
    Exiting the application or terminating the GDL session via a call to
    gdl_close() without freeing the surface will result in its automatic
    deallocation. A warning message will be printed to the system console and
    log.
    */

GDL_API gdl_ret_t
gdl_get_surface_info(
    gdl_surface_id_t     surface_id,
    gdl_surface_info_t * surface_info
    );
    /**< @ingroup surface

    This routine returns the gdl_surface_info_t data structure for the requested
    surface.

    @param [in] surface_id
    The ID of the surface for which information is requested.

    @param [out] surface_info
    A pointer to a #gdl_surface_info_t structure to be filled with information
    about the specified surface.
    */

GDL_API gdl_ret_t
gdl_flush_surface(
    gdl_surface_id_t surface_id
    );
    /**< @ingroup surface

    This routine flushes cached memory used by the surface. Flushing only has any
    effect when surface is allocated with #GDL_SURFACE_CACHED flag.

    @param [in] surface_id
    The ID of the surface to be flushed.
    */

GDL_API gdl_ret_t
gdl_map_surface(
    gdl_surface_id_t surface_id,
    gdl_uint8 **     pointer,
    gdl_uint32 *     pitch
    );
    /**< @ingroup surface

    This routine provides a direct pointer to the surface's buffer mapped into
    the caller's address space. Synchronization of any graphics operations
    pending on that surface must be handled by the caller before using the
    pointer.

    A surface may be mapped by more than one thread.

    The surface must be unmapped prior to freeing it; an attempt to free a
    mapped surface will fail.

    @param [in] surface_id
    The ID of the surface that to be mapped.

    @param [out] pointer
    CPU accessible address of the surface.

    @param [out] pitch
    The pitch of the mapped surface in bytes.  This is an optional output
    parameter and will be ignored if it is NULL.  In the case of a YUV
    planar or pseudo-planar surface, this is the pitch of the Y surface.
    */

GDL_API gdl_ret_t
gdl_unmap_surface(
    gdl_surface_id_t surface_id
    );
    /**< @ingroup surface

    This routine unmaps the surface's buffer from the callers address space.
    All surfaces should be unmapped when the pointer is no longer needed.
    An attempt to free a mapped surface will fail.

    @param [in] surface_id
    The ID of the surface that is to be unmapped.
    */

GDL_API gdl_ret_t
gdl_free_surface(
    gdl_surface_id_t surface_id
    );
    /**< @ingroup surface

    This routine destroys the memory associated with the specified surface.

    @param [in] surface_id
    The ID of the surface that to be destroyed.

    @b NOTE
    - Freeing a surface that is currently being displayed on a plane, will cause
      the plane to be disabled. A warning will be printed to the system console
      and log.

    - Attempting to free a surface that is currently mapped by anyone will
      result in a #GDL_ERR_MAPPED error.

    - Passing an invalid surface ID or the ID GDL_SURFACE_INVALID will result in
      an error return.
    */

GDL_API gdl_ret_t
gdl_get_palette(
    gdl_surface_id_t surface_id,
    gdl_palette_t *  palette
    );
    /**< @ingroup surface

    This routine returns the palette entries for the specified surface.

     @param [in] surface_id
     The ID of the surface whose palette entries are to be returned.

     @param [in,out] palette
     The length field of the palette structure contains the number of palette
     entries requested by the user. Upon completion of this call it may be
     updated with the actual number of palette entries (if less than the
     specified length) or with zero(if there is no palette associated with the
     surface). The data field will be filled with palette entries.
     */

GDL_API gdl_ret_t
gdl_set_palette(
    gdl_surface_id_t surface_id,
    gdl_palette_t *  palette
    );
    /**< @ingroup surface

    This routine assigns the specified palette to the specified surface.
    An error will be returned if the pixel format of the surface is not a
    palettized format.

    Note that the palette info is copied into the driver: changing entries in
    a palette has no effect until the next time gdl_set_palette() is called.

    Also note that changing the palette of a surface that is currently flipped
    onto a plane does <b>not</b> change the displayed colors: the surface
    must be flipped onto the plane again after the palette is set.

    @param [in] surface_id
    The ID of the surface whose palette entries will be set.

    @param [in] palette
    A pointer to a palette structure containing color data as well as number
    of active palette elements
    */

GDL_API gdl_ret_t
gdl_get(
    gdl_surface_id_t  surface_id,
    gdl_rectangle_t * rect,
    gdl_uint32        pitch,
    gdl_void *        data,
    gdl_uint32        flags
    );
    /**< @ingroup surface

    This routine copies a rectangular region of pixel data out of a surface to
    a buffer.

    @param [in] surface_id
    The ID of the surface from which the pixel data is read. This function is
    currently only implemented for the following pixel formats, and will return
    an error code if the surface has any other pixel format:
    - GDL_PF_ARGB_32
    - GDL_PF_RGB_32
    - GDL_PF_RGB_24
    - GDL_PF_ARGB_16_4444
    - GDL_PF_RGB_16
    - GDL_PF_RGB_15

    @param [in] rect
    The rectangle within the surface from which the data is to be read.
    The origin is relative to the origin of the surface.  Both the origin
    coordinates and the dimensions of the rectangle are specified in pixels.
    A NULL pointer indicates that the rectangle is the entire surface.

    @param [in] pitch
    The pitch of the output data buffer. It must be greater than or equal to
    @code
    rect->width * <bytes-per-pixel>
    @endcode

    @param [out] data
    The address of the buffer to which the pixel data should be copied.
    The size of the buffer must be greater than or equal to
    @code
    rect->height * pitch
    @endcode

    @param [in] flags
    None currently defined -- pass as 0.
    */

GDL_API gdl_ret_t
gdl_put(
    gdl_surface_id_t  surface_id,
    gdl_rectangle_t * rect,
    gdl_uint32        pitch,
    gdl_void*         data,
    gdl_uint32        flags
    );
    /**< @ingroup surface

    This routine copies a rectangular region of pixel data into a surface from
    a buffer.

    @param [in] surface_id
    The ID of the surface to which the pixel data will be written.  This
    function is currently only implemented for the following pixel formats, and
    will return an error code if the surface has any other pixel format:
    - GDL_PF_ARGB_32
    - GDL_PF_RGB_32
    - GDL_PF_RGB_24
    - GDL_PF_ARGB_16_4444
    - GDL_PF_RGB_16
    - GDL_PF_RGB_15

    @param [in] rect
    The rectangle within the surface to which the data is to be written.
    The origin is relative to the origin of the surface.  Both the origin
    coordinates and the dimensions of the rectangle are specified in pixels.
    A NULL pointer indicates that the rectangle is the entire surface.

    @param [in] pitch
    The pitch of the input data buffer. It must be greater than or equal to
    @code
    rect->width * <bytes-per-pixel>
    @endcode

    @param [in] data
    The address of the buffer from which the pixel data should be copied.
    The pixel format of the data is assumed to be that of the surface.
    The size of the buffer must be greater than or equal to
    @code
    rect->height * pitch
    @endcode

    @param [in] flags
    None currently defined -- pass as 0.
    */

GDL_API gdl_ret_t
gdl_clear_surface(
    gdl_surface_id_t surface_id,
    gdl_color_t *    color
    );
    /**< @ingroup surface

    This routine clears a surface by setting all of its pixels to the specified
    color.

    @param [in] surface_id
    The ID of the surface to be cleared.  Only packed pixel formats are
    supported by this function;  if the surface has a pseudo-planar video pixel
    format, the call will fail.

    @param [in] color
    The input color for the operation. Note that:
    - The pixel format of the surface will determine which fields and bits
      of the gdl_color_t item are used.  For example, if the pixel format is
      GDL_PF_RGB_16, then:
      - none of the alpha_index field will be used.
      - the low-order 5 bits of the r_y field will be used.
      - the low-order 6 bits of the g_u field will be used.
      - the low-order 5 bits of the b-v field will be used.
      .
    - If the surface is supposed to contain pixels with premultiplied alpha
      it is the programmer's responsibility to pass a color whose components
      have been premultiplied.
    */

GDL_API gdl_ret_t
gdl_plane_capabilities(
    gdl_plane_id_t     plane_id,
    gdl_plane_info_t * info
    );
    /**< @ingroup plane_management

    This function returns information about the hardware capabilities of the
    specified display plane.

    The returned data structure will report the plane name, the
    programmer-configurable attributes, and the pixel formats supported by the
    plane.  See #gdl_plane_info_t to determine how to interpret the returned
    information.

    @param [in]  plane_id
    The ID of the plane for which information should be returned.

    @param [out] info
    Plane information is returned here.
    */

GDL_API gdl_ret_t
gdl_plane_config_begin(
    gdl_plane_id_t plane_id
    );
    /**< @ingroup plane_management

    This function begins a configuration transaction for the specified plane.

    After making this call, the application program can call the gdl_plane_set_*
    functions to change the attributes of interest.  No new attribute values
    are actually set in the hardware until a call is made to
    gdl_plane_config_end().

    The "batching" of attribute settings reduces the number of round trips
    made to the driver and helps avoid invalid intermediate states when
    interrelated attributes are being changed.

    Only one transaction can be open at a time.  If a corresponding call to
    gdl_plane_config_end() is not made before the next call to
    gdl_plane_config_begin(), an error will be returned.

    @param [in]  plane_id
        The ID of the plane for which a configuration transaction should be
        begun.

    @see gdl_plane_config_end(), gdl_plane_set_uint(), gdl_plane_set_int(),
         gdl_plane_set_rect(), gdl_plane_set_attr(),
    */


GDL_API gdl_ret_t
gdl_plane_config_end(
    gdl_boolean_t abort
    );
    /**< @ingroup plane_management

    This function delimits the end of a configuration transaction.  All
    attributes specified via gdl_plane_set_* calls since the last call to
    gdl_plane_config_begin() are validated and applied.

    The 'abort' argument causes all pending configuration settings to be
    discarded without being applied.

    It is an error to call this function without a preceding call to
    gdl_plane_config_begin().  If this function is called with abort=#GDL_TRUE,
    the return value can be safely ignored and the caller is guaranteed that
    there are no configuration operations pending or in progress for the calling
    application.

    @param [in] abort
        If #GDL_FALSE, all plane attributes set since the last call to
        gdl_plane_config_begin() are validated and applied.  Otherwise, all
        pending settings are discarded and the transaction is terminated
        without any change to the hardware.

    @see gdl_plane_config_begin()
    */

GDL_API gdl_ret_t
gdl_plane_set_int(
    gdl_plane_attr_t name,
    gdl_int32        value
    );
    /**< @ingroup plane_management
         See gdl_plane_set_attr()
    */

GDL_API gdl_ret_t
gdl_plane_set_uint(
    gdl_plane_attr_t name,
    gdl_uint32       value
    );
    /**< @ingroup plane_management
         See gdl_plane_set_attr()
    */

GDL_API gdl_ret_t
gdl_plane_set_rect(
    gdl_plane_attr_t  name,
    gdl_rectangle_t * value
    );
    /**< @ingroup plane_management
         See gdl_plane_set_attr()
    */


GDL_API gdl_ret_t
gdl_plane_set_attr(
    gdl_plane_attr_t name,
    void *           value
    );
    /**< @ingroup plane_management
    These functions queue the specified attribute setting for execution in the
    currently open configuration transaction.  They vary from each other only
    in the type of value they accept, which must be appropriate for the
    specified attribute.

    It is an error to call any of these functions with the "name" of an
    attribute that has a type different from that of the function.

    It is an error to call any of these functions without a preceding call to
    gdl_plane_config_begin().

    The plane is not actually reconfigured until the next call to
    gdl_plane_config_end().  It is possible that an error caused by passing
    erroneous or conflicting values to the "set" functions will not be
    detected until then.

    Note that data values passed to these routines are cached -- the
    application does @b not need to preserve the data or pointers until the
    gdl_plane_config_end() is called.

    @param [in] name
        The attribute to be changed.

    @param [in] value
        The new setting (or, for multi-word values, pointer to the new setting)
        for the attribute.

    @see gdl_plane_config_begin(),  gdl_plane_config_end()
    */

GDL_API gdl_ret_t
gdl_plane_get_int(
    gdl_plane_id_t   plane,
    gdl_plane_attr_t name,
    gdl_int32 *      value
    );
    /**< @ingroup plane_management
     See gdl_plane_get_attr()
    */

GDL_API gdl_ret_t
gdl_plane_get_uint(
    gdl_plane_id_t   plane,
    gdl_plane_attr_t name,
    gdl_uint32 *     value
    );
    /**< @ingroup plane_management
      See gdl_plane_get_attr()
    */

GDL_API gdl_ret_t
gdl_plane_get_rect(
    gdl_plane_id_t    plane,
    gdl_plane_attr_t  name,
    gdl_rectangle_t * value
    );
    /**< @ingroup plane_management
      See gdl_plane_get_attr()
    */

GDL_API gdl_ret_t
gdl_plane_get_attr(
    gdl_plane_id_t   plane,
    gdl_plane_attr_t name,
    void *           value
    );
    /**< @ingroup plane_management
    These functions retrieve the current value of the specified attribute
    for the specified plane.  These functions vary from each other only in the
    type of value they return.

    It is an error to call any of these functions with the "name" of an
    attribute that has a type different from that of the function.

    @param [in] plane
        The plane to be queried.

    @param [in] name
        The attribute whose value is to be retrieved.

    @param [out] value
        The current value of the attribute is returned here.
    */

GDL_API gdl_ret_t
gdl_plane_reset(
    gdl_plane_id_t plane
    );
    /**< @ingroup plane_management
    Disables the specified plane and resets its attributes to their defaults.

    @param [in] plane
        The plane to be reset.
    */

GDL_API gdl_ret_t
gdl_plane_reset_all(
    void
    );
    /**< @ingroup plane_management
    Disables all planes and reset their attributes to their defaults.
    */

GDL_API gdl_ret_t
gdl_flip(
    gdl_plane_id_t   plane_id,
    gdl_surface_id_t surface_id,
    gdl_flip_t       sync
    );
    /**< @ingroup plane_management

    This function makes a specified surface visible on the specified plane.
    The pixel format and dimensions of the surface must match the current
    configuration of the plane.

    @param [in] plane_id
    The plane onto which the surface should be flipped.

    @param [in] surface_id
    The ID of the surface to be flipped onto the plane, normally returned by
    gdl_alloc_surface().  If the surface ID is #GDL_SURFACE_INVALID, the plane
    will be disabled; otherwise, the plane is enabled if necessary.

    @param [in] sync
    Determines how flipping of the surface is synchronized with the caller.
    See the description of #gdl_flip_t for details.

    @b NOTE
    - If the client that allocated a displayed surface exits,
      deallocates the surface or calls #gdl_close, then the plane on which
      the surface was flipped will automatically be disabled.
    */


GDL_API gdl_ret_t
gdl_port_pd_load(
    char *     pd_name,
    gdl_uint32 args_num,
    char **    args
    );
    /**< @ingroup  disp_pd

    Load a port driver and optionally pass it arguments.

    @param [in] pd_name
    Name of port driver (specified as path to the port driver .so file).

    @param [in] args_num
    Number of supplied arguments.

    @param [in] args
    Array of arguments, where each argument is a string of the form
    "<attr>=<value>".
    */

GDL_API gdl_ret_t
gdl_port_pd_unload(
    char *pd_name
    );

    /**< @ingroup  disp_pd

    Unload a port driver.

    @param [in] pd_name
    Name of the port driver (specified as the name of its .so file, but
    without the .so extension).
    */

GDL_API gdl_ret_t
gdl_port_set_attr(
    gdl_pd_id_t           pd_id,
    gdl_pd_attribute_id_t attribute_id,
    void *                attribute_value
    );
    /**< @ingroup disp_pd

    Set the current value of a port driver attribute.

    @param [in] pd_id
    Port driver ID.

    @param [in] attribute_id
    Attribute ID.

    @param [in] attribute_value
    Pointer to value to which attribute should be set.
    */

GDL_API gdl_ret_t
gdl_port_get_attr(
    gdl_pd_id_t           pd_id,
    gdl_pd_attribute_id_t attribute_id,
    gdl_pd_attribute_t *  attribute
    );
    /**< @ingroup disp_pd

    Retrieve the current value of a port driver attribute.

    @param [in] pd_id
    Port driver ID.

    @param [in] attribute_id
    Attribute ID.

    @param [out] attribute
    Attribute value returned here.
    */

GDL_API gdl_ret_t
gdl_port_send(
    gdl_pd_id_t   pd_id,
    gdl_pd_send_t data_id,
    void *        data,
    unsigned int  data_size
    );
    /**< @ingroup disp_pd

    Send port-specific data to a port driver. This function allows the sending
    of port-specific data structures, which in turn may kick off device-specific
    operations.

    @param [in] pd_id
    Port driver ID.

    @param [in] data_id
    An identifier indicating the kind of data structure being sent.  Based
    on this ID, the port driver will determine the format of the data and the
    operation to be performed.  See the description of #gdl_pd_send_t for more
    details.

    @param [in] data
    Pointer to the beginning of the data structure to be sent.

    @param [in] data_size
    Size of the data structure in bytes.
    */

GDL_API gdl_ret_t
gdl_port_recv(
    gdl_pd_id_t   pd_id,
    gdl_pd_recv_t data_id,
    void *        data,
    unsigned int  data_size
    );
    /**< @ingroup disp_pd

    Retrieve port-specific data from a port driver.

    @param [in] pd_id
    Port driver ID.

    @param [in] data_id
    An identifier indicating the kind of data structure to be returned.  Based
    on this ID, the port driver will determine how to retrieve the data and
    how to format it for output.  See the description of #gdl_pd_recv_t for
    more details.

    @param [out] data
    The data structure is returned here.

    @param [in] data_size
    Size, in bytes, of the output buffer pointed at by 'data'.
    */

GDL_API char *
gdl_get_error_string(
    gdl_ret_t gdl_ret
    );
    /**< @ingroup debug

    This function returns a character string representation of the passed
    enumerator.

    @param [in] gdl_ret
    A GDL return value.
    */

GDL_API void
gdl_dbg_dump_display_info(
    gdl_display_info_t * d
    );
    /**< @ingroup debug

    This function prints the content of the specified #gdl_display_info_t to
    stdout.

    @param [in] d
    The structure whose contents are to be printed
    */

GDL_API void
gdl_dbg_dump_surface_info(
    gdl_surface_info_t * s
    );
    /**< @ingroup debug

    This function prints the content of the specified #gdl_surface_info_t to
    stdout.

    @param [in] s
    The structure whose contents are to be printed
    */

GDL_API char *
gdl_dbg_string_attribute(
    gdl_plane_attr_t attr
    );
    /**< @ingroup debug

    This function returns a pointer to a 0-terminated string representation of a
    plane attribute ID.

    @param [in] attr
    The ID for which the string should be returned.
    */

GDL_API char *
gdl_dbg_string_pixel_format(
    gdl_pixel_format_t pf
    );
    /**< @ingroup debug

    This function returns a pointer to a 0-terminated string representation of a
    pixel format ID.

    @param [in] pf
    The ID for which the string should be returned.
    */

GDL_API char *
gdl_dbg_string_plane_id(
    gdl_plane_id_t pid
    );
    /**< @ingroup debug

    This function returns a pointer to a 0-terminated string representation of a
    plane ID.

    @param [in] pid
    The plane ID for which the string should be returned.
    */

GDL_API char *
gdl_dbg_string_refresh(
    gdl_refresh_t r
    );
    /**< @ingroup debug

    This function returns a pointer to a 0-terminated string representation of a
    display refresh rate enumerator.

    @param [in] r
    The enumerator for which the string should be returned.
    */

GDL_API char *
gdl_dbg_string_sampling_rate(
    gdl_hdmi_audio_fs_t fs
    );
    /**< @ingroup debug

    This function returns a pointer to a 0-terminated string representation of an
    HDMI audio sampling rate enumerator.

    @param [in] fs
    The enumerator for which the string should be returned.
    */

GDL_API char *
gdl_dbg_string_sample_size(
    gdl_hdmi_audio_ss_t ss
    );
    /**< @ingroup debug

    This function returns a pointer to a 0-terminated string representation of an
    HDMI audio sample size enumerator.

    @param [in] ss
    The enumerator for which the string should be returned.
    */


GDL_API char *
gdl_dbg_string_audio_format(
    gdl_hdmi_audio_fmt_t fmt
    );
    /**< @ingroup debug

    This function returns a pointer to a 0-terminated string representation of an
    HDMI audio format enumerator.

    @param [in] fmt
    The enumerator for which the string should be returned.
    */

GDL_API char *
gdl_dbg_string_speaker_map(
    gdl_hdmi_audio_speaker_map_t map
    );
    /**< @ingroup debug

    This function returns a pointer to a 0-terminated string representation of an
    HDMI speaker allocation enumerator.

    @param [in] map
    The enumerator for which the string should be returned.
    */

GDL_API gdl_ret_t
gdl_event_register(
    gdl_app_event_t      event,
    gdl_event_callback_t callback,
    void *               user_data
    );
    /**< @ingroup general
    This function registers a callback function for the specified event, 
    causing the function to be called every time the event occurs.

    Only one callback may be registered for a particular event.
    however, the same callback function can be registered for multiple events.
    The event which triggered the callback will be passed to the function
    when it is evoked.

    The callback function will be called asynchronously and should take the
    necessary precautions to prevent contention for global data structures.
    Callback functions do not have to be re-entrant: once any callback has
    been invoked for an event, all other events are put on hold until the
    callback returns. This could require the function to register the event
    with the application for synchronous processing and return to the caller
    ASAP.
    
    Every time a callback function is called it will be passed 'user_data'.
    
    @param [in] event
    Event of interest.

    @param [in] callback
    Callback function

    @param [in] user_data
    User data that will be passed into a callback function.
    */

GDL_API gdl_ret_t
gdl_event_unregister(
    gdl_app_event_t    event
    );
    /**< @ingroup general
    This function unregisters the callback from being called for a specified event.
    Since the same callback function can be registered for more than one event, 
    other events will continue triggering an execution of the callback function.
    
    @param [in] event
    Event of interest
    */

GDL_API gdl_ret_t
gdl_debug_log_start(
    char *       filename,
    unsigned int flags
    );
    /**< @ingroup debug
    This function begins logging of function calls within the GDL daemon.
    This type of logging is primarily intended for use by GDL driver developers
    in trouble-shooting problems.
    
    @param [in] filename
    The pathname of the file to which the log information will be written.  If
    a file with the same pathname already exists, it will be deleted before
    logging begin.

    @param [in] flags
    The type of information that should be logged, passed as the OR-ed
    combination members of the #gdl_log_flag_t enumeration.
    */

GDL_API gdl_ret_t
gdl_debug_log_stop(
    void
    );
    /**< @ingroup debug
    This function terminates driver-side logging previously started with
    gdl_debug_log_start().
    */


GDL_API gdl_ret_t
gdl_create_surface(
    gdl_surface_info_t * surface_info
    );
    /**< @ingroup surface
    This function allows a surface to be created from memory allocated outside of
    the display driver.
    
    The memory must be @b physically contiguous, and must remain available until
    after the surface is freed.
 
    @param [in,out] surface_info
    The surface information used to create the GDL surface.  The @b physical
    address of the start of the memory must be passed in the
    'surface_info.phys_addr' field.  @b All other fields must be correctly
    filled before the structure is passed to this function, with the
    exception of the following:
    - id:  will be filled in with a value surface ID upon successful return
      from this function.
    - heap_phys_addr: will be ignored and overwritten by this function.
    */


GDL_API gdl_ret_t
gdl_attach_heap(
    const char * heap_name
    );
    /**< @ingroup surface
    This function makes the specified heap available for allocation of surfaces
    in the calling process via #gdl_alloc_surface().
    
    heap_name must appear in the platform configuration file under the node 
    'platform.startup.memory.layout'. The memory whose physical
    base address and size are specified there will be made available to the
    calling process.

    Once a heap is attached to a process, the display driver may satisfy surface
    allocation requests from either its default (static) heap or the attached
    one.

    Multiple processes may attach the same heap. A process may attach multiple
    heaps. An error will be returned if a process tries to attach to two
    differnt heaps that overlap.

    There is no need to de-attach a heap; it is sufficient to free all surfaces
    allocated by the process. The display driver will automatically free any
    remaining surfaces allocated by a proces when #gdl_close() is called.

    An attached heap is available to a process from the moment it is attached
    until the GDL session for the process is terminated.

    This function allows device memory (physical memory beyond the end of the
    operating system) normally reserved for video playback to be reallocated
    at runtime for use by graphics-intensive operations. It is expected that
    the controlling application will terminate video playback to make the 
    memory available before starting a graphics-intensive application that
    will attach the heap. The controlling application itself should not
    attach the memory as there will be no way to relinquish it when the 
    graphics application stops and it is time to play video again
    
    @param [in] heap_name
    The name of the heap as it appears in the platform configuration file under
    the 'platform.startup.memory.layout' node.
    */


GDL_API gdl_ret_t
gdl_heap_in_use(
    const char    * heap_name,
    gdl_boolean_t * status
    );
    /**< @ingroup surface
    This function determines whether any surfaces are currently allocated from 
    the specified heap.

    Returns status GDL_FALSE if no surfaces are currently allocated from the
    specified heap or GDL_TRUE otherwise. Fails if the heap name does not
    appear in the platform configuration file.

    @param [in] heap_name
    A name of the heap as it appears in platform configuration file under the
    'platform.startup.memory.layout'. 

    @param [out] status
    Returned status.
    */


#if defined(__cplusplus)
};
#endif

#endif