NativeWindowFactory:

    - If property 'nativewindow.ws.name' is set,
      use it as the custom windowing type returned by
      getNativeWindowType(true)

NEWT:
    - Using NativeWindowFactory's property 'nativewindow.ws.name'
      as a package name for custom NEWT windowing imlementations,
      ie:
        -Dnativewindow.ws.name=com.sun.javafx.newt.intel.gdl
        -Dnativewindow.ws.name=com.sun.javafx.newt.broadcom.egl
      This allows far more flexibility to add custom impl.

    - Add Intel-GDL, define property 'useIntelGDL'
      to build the native part.
      Intel GDL is impl in the package 'com.sun.javafx.newt.intel.gdl'

JOGL:
    - All impl. of 'createGLDrawable(..)', which were actually creating
      onscreen drawable only, were renamed to 'createOnscreenDrawable(..)'.

    - GLDrawableFactoryImpl impl. 'createGLDrawable(..)' now
      and dispatches to the actual create* methods in respect to
      the Capabilities, ie onscreen, pbuffer and offscreen.

    - GLDrawableFactory:
        - If using a native ES profile -> EGLDrawableFactory
        - If existing native OS factory -> Use that ..
        - Else -> Use EGLDrawableFactory, if available

1 files changed, 1329 insertions, 0 deletions

diff --git a/make/stub_includes/embedded/IntelGDL/gdl.h b/make/stub_includes/embedded/IntelGDL/gdl.h
new file mode 100644
index 000000000..f1990349c
--- /dev/null
+++ b/make/stub_includes/embedded/IntelGDL/gdl.h
@@ -0,0 +1,1329 @@
+//-----------------------------------------------------------------------------
+// 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