diff options
Diffstat (limited to 'make/stub_includes/embedded/IntelGDL/gdl.h')
| -rw-r--r-- | make/stub_includes/embedded/IntelGDL/gdl.h | 1329 |
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 |