DVD

开发平台：
C/C++

machblue_porting_core.h：源码内容
							/*-----------------------------------------------------------------------------
 | @(#) machblue_porting_core.h
 |
 |  JSWF: The Portable SWF Engine For Embedded Devices,
 |  Copyright (c) 2002-2006, BlueStreak Technology Inc., All Rights Reserved.
 |
 +----------------------------------------------------------------------------*/
#ifndef _MACHBLUE_PORTING_CORE_H_
#define _MACHBLUE_PORTING_CORE_H_
/*----------------------------------------------------------
 | Include definition below this line
 +----------------------------------------------------------*/
#include "machblue_defines.h"
#include "machblue_customer.h"
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/*----------------------------------------------------------
 | Macro definition below this line
 +----------------------------------------------------------*/
/*----------------------------------------------------------
 | Type definition below this line
 +----------------------------------------------------------*/
/*----------------------------------------------------------
 | Functions definition below this line
 +----------------------------------------------------------*/
/*
 * ======================= Porting Layer Init API ===========================================
 */
/** @defgroup init_group Porting Layer Init API
 *  @{
 * This API is used by Machblue to initialize or delete the 
 * core porting layer.
 */
/**
 * Invoked by Machblue to initialize the porting layer. This
 * will be called before any calls to the porting layer.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_porting_layer_init
( 
    void *init_client_data /**< platform specific init client data specified in mb_init_config_t */
);
/**
 * Invoked by Machblue to delete the porting layer. Machblue will 
 * not make any calls to the porting layer after this call
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_porting_layer_delete( void );
/** @} */
/*
 * ======================= Memory Allocation API ===========================================
 */
/** @defgroup memory_alloc_group Memory Allocation API
 *  @{
 * This API is used by Machblue to allocate memory from the platform.
 */
/**
 * Allocates a memory chunk from the system heap. This function will only be called
 * if Machblue's heap is initialized as growable. 
 * @return an aligned pointer to the allocated memory chunk on success or NULL on failure.
 */
extern void *mb_malloc
( 
    mb_size_t size  /**< size to allocate in bytes */
);
/**
 * Deletes a previously allocated memory chunk.
 * @return none.
 */
extern void mb_free
( 
    void *ptr /**< previously allocated memory chunk to free */
);
/** @} */
/*
 * ======================= Moveable Memory Block Allocation API ===========================================
 */
/** @defgroup memory_block_alloc_group Moveable Memory Block Allocation API
 *  @{
 * This API is used by Machblue to allocate moveable memory blocks from 
 * the platform.
 */
/**
 * Allocates a movable memory block from the system heap.
 * On systems that do not support movable memory blocks, MB_FAILURE
 * should be returned. This function  will only be called if Machblue's heap 
 * is initialized as growable. 
 * @return MB_SUCCESS and updates "mem_block" on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_mem_block_alloc
( 
    mb_size_t       size,      /**< size to allocate in bytes */
    mb_mem_block_t *mem_block /**< pointer to mem block to allocate */
);
/**
 * Deletes a previously allocated memory block.
 * @return none.
 */
extern void mb_mem_block_free
( 
    mb_mem_block_t mem_block /**< previously allocated memory block handle to free */
);
/**
 * Locks (pins) a memory block in memory. 
 * @return MB_SUCCESS and sets locked_prt to an aligned pointer to the 
 * allocated memory block on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_mem_block_lock
( 
    mb_mem_block_t   mem_block,  /**< memory block handle to lock */
    void           **locked_ptr  /**< pointer to location to store pointer to locked memory block */
);
/**
 * Unlocks (unpins) a memory block
 * @return none.
 */
extern void mb_mem_block_unlock
( 
    mb_mem_block_t mem_block /**< memory block handle to unlock */
);
/** @} */
/*
 * ======================= Synchronization API ===========================================
 */
/** @defgroup synchronization_group Synchronization API
 *  @{
 * This API is used by Machblue to access the platform's synchronization
 * api.
 */
/**
 * Creates a new semaphore.
 * @return MB_SUCCESS and updates "semaphore" or MB_FAILURE on failure.
 */
extern mb_error_t mb_semaphore_create
( 
    mb_semaphore_t *semaphore,    /**< pointer to semaphore to create */
    unsigned int    initial_value /**< initial number of resource */
);
/**
 * Deletes a semaphore.
 * @return MB_SUCCESS on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_semaphore_delete
( 
    mb_semaphore_t semaphore /**< semaphore to delete */
);
/**
 * Signals a counting semaphore (V).
 * @return MB_SUCCESS on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_semaphore_signal
( 
    mb_semaphore_t semaphore /**< counting semaphore to signal */
);
/**
 * Waits on a counting semaphore (P).
 * @return MB_SUCCESS on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_semaphore_wait
( 
    mb_semaphore_t semaphore  /**< Semaphore to wait on */
);
/**
 * Tries to wait on a semaphore (non-blocking). Returns immediatly 
 * (does not block) if the semaphore has a zero count otherwise atomically 
 * decreases count (consumes the resource). 
 * @return MB_SUCCESS on success, MB_BUSY if the semaphore count is zero
 * or MB_FAILURE on failure.
 */
extern mb_error_t mb_semaphore_trywait
( 
    mb_semaphore_t semaphore  /**< Semaphore to wait on */
);
/**
 * Creates a new mutex. This should maps to the fast mutex implementation 
 * (a.k.a. non reccursive mutex) on the platform.
 * @return MB_SUCCESS and update "mutex" on success, or MB_FAILURE on failure.
 */
extern mb_error_t mb_mutex_create
(
    mb_mutex_t *mutex /**< pointer to mutex to create */
);
/**
 * Deletes a mutex.
 * @return MB_SUCCESS on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_mutex_delete
( 
    mb_mutex_t mutex /**< mutex to delete */
);
/**
 * Locks a mutex.
 * @return MB_SUCCESS on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_mutex_lock
( 
    mb_mutex_t mutex  /**< mutex to lock */
);
/**
 * Unlocks a mutex
 *
 * @return MB_SUCCESS on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_mutex_unlock
( 
    mb_mutex_t mutex /**< mutex to unlock */
);
/**
 * Tries to lock a mutex (non-blocking). Returns immediatly (does 
 * not block) if the mutex is already locked otherwise locks it.
 *
 * @return MB_SUCCESS on success, MB_BUSY if the mutex is already locked
 * or MB_FAILURE on failure.
 */
extern mb_error_t mb_mutex_trylock
( 
    mb_mutex_t mutex  /**< mutex to lock */
);
/** @} */
/*
 * ======================= Thread API ===========================================
 */
/** @defgroup thread_group Thread API API
 *  @{
 * This API is used by Machblue to access the platform's thread api.
 */
/**
 * Creates a new thread.
 * @return a MB_SUCCESS and updates "tid" on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_thread_create
( 
    mb_tid_t                    *tid,            /**< pointer to location to store new thread id */
    mb_thread_attributes_t      *thread_attrib,  /**< pointer to attributes of thread to create */
    mb_thread_start_function_t  *start_function, /**< pointer to thread start function */
    void                        *arg             /**< pointer to argument to pass to start function */
);
/**
 * Deletes a thread. This simply deletes the handle to the 
 * trhead on platforms that have such a notion. The thread should 
 * not be killed as a result of this call.
 * @return MB_SUCCESS on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_thread_delete
( 
    mb_tid_t tid  /**< tid of thread to delete */
);
/**
 * Joins (waits for completion of) a thread.
 * @return MB_SUCCESS on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_thread_join
( 
    mb_tid_t tid /**< tid of thread to join */ 
);
/**
 * Gets the current thread id.
 * @return MB_SUCCESS and updates tid on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_thread_id_get
( 
    mb_tid_t *tid /**< pointer to location to store current thread id */
);
/** @} */
/*
 * ======================= Message Passing API ===================
 */
/** @defgroup message_group Message Passing API
 *  @{
 * This API is used by Machblue to access the platform's message passing 
 * api.
 */
/**
 * Posts a message to a thread.
 * @return MB_SUCCESS on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_msg_post
( 
    mb_tid_t         tid, /**< tid to post message to */ 
    mb_message_t    *msg  /**< pointer to message to post */
);
/**
 * Waits for a message in the current thread mesasge queue.
 * @return MB_SUCCESS on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_msg_wait
( 
    mb_message_t *msg  /**< msg structure used to store received message */
);
/**
 * Gets a message from the current thread message queue without waiting.
 * If the queue is empty it @return immediatly.
 * @return MB_SUCCESS if a message was successfully retrieved, MB_FAILURE otherwise.
 */
extern mb_error_t mb_msg_get_no_wait
( 
    mb_message_t *msg  /**< msg structure used to store received message */
);
/** @} */
/*
 * ======================= Timer API ===========================================
 */
/** @defgroup timer_group Timer API
 *  @{
 * This API is used by Machblue to access the platform's timer 
 * api.
 */
/**
 * Sets Machblue's timer. The timer callback function should be invoked when
 * the specified delay expires. Machblue will only schedule one timer at a time.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_timer_set
(
    long                 delay,          /**< timer delay in milliseconds */
    mb_timer_callback_f *callback_f,     /**< timer callback function */
    void                *cb_client_data  /**< timer callback function client data */
);
/**
 * Cancels Machblue's timer request.
 * This function cancels Machblue's timer request.
 */
extern mb_error_t mb_timer_cancel( void );
/** @} */
/*
 * ======================= Memory Utility API ===========================================
 */
/** @defgroup memory_util_group Memory Utility API
 *  @{
 * This API is used by Machblue to access the platform's memory utility 
 * api.
 */
/**
 * Sets a memory block to a given pattern.
 * @return none.
 */
extern void mb_memset
( 
    void      *ptr,      /**< pointer to memory block to set */
    int        pattern,  /**< pattern to set */ 
    mb_size_t  n         /**< number of bytes to set */
);
/**
 * Moves n bytes from src to dest.
 * @return none.
 */
extern void mb_memmove
( 
    void       *dest,   /**< destination to move bytes to */
    const void *src,    /**< source to move bytes from */
    mb_size_t   n       /**< numbers of bytes to move */
);
/**
 * Copies n bytes from src to dest.
 * @return none.
 */
extern void mb_memcpy
( 
    void       *dest, /**< destination to copy bytes to */
    const void *src,  /**< source to copy bytes from */
    mb_size_t   n     /**< numbers of bytes to copy */
);
/**
 * Compares n bytes from ptr1 against ptr2.
 * @return none.
 */
extern int mb_memcmp
( 
    const void *ptr1, /**< pointer to first memory block to compare */
    const void *ptr2, /**< pointer to second memory block to compare */
    mb_size_t   n     /**< number of bytes to compare */
);
/** @} */
/*
 * ======================= String API ===========================================
 */
/** @defgroup string_group String API
 *  @{
 * This API is used by Machblue to access the platform's string formatting 
 * api.
 */
/**
 * Converts letter to upper case.
 * @return upper case letter (locale dependent).
 */
extern int mb_toupper
( 
    int c /**< character to convert */
);
/**
 * Converts letter to lower case.
 * @return lower case letter (locale dependent).
 */
extern int mb_tolower
( 
    int c /**< character to convert */
 );
/**
 * Prints a formated string based on the specified format. The output
 * is stored in the provided string.
 * @return the number of characters printed.
 */
extern int mb_sprintf
( 
    mb_char_t       *str,    /**< destination string */
    const mb_char_t *format, /**< printf format specification string */
    ...                      /**< argument list */
);
/**
 * Prints a formated string based on the specified format. The intended output
 * is stdout. It may be redirected at the customer discretion.
 * @return the number of characters printed.
 */
extern int mb_printf
( 
    const mb_char_t *format, /**< printf format specification string */
    ...                      /**< argument list */ 
);
/**
 * Prints a formated string based on the specified format (variable argument 
 * list version). The output is stored in the provided string.
 * @return the number of characters printed.
 */
extern int mb_vsprintf
( 
    mb_char_t       *str,       /**<  destination string */
    const mb_char_t *format,    /**< printf format specification string */
    va_list          args       /**<  argument list*/
);
/**
 * Prints a formated string based on the specified format(variable argument 
 * list version). The intended output is stdout. It may be redirected at the
 * customer discretion.
 * @return the number of characters printed.
 */
extern int mb_vprintf
( 
    const mb_char_t *format,  /**< printf format specification string  */
    va_list          args     /**< argument list */
);
/** @} */
/*
 * ======================= Math API ===========================================
 */
/** @defgroup math_group Math API
 *  @{
 * This API is used by Machblue to access the platform's math api.
 * This api not used for critical operations in the player. So
 * a software fpu implementation is acceptable.
 */
/**
 * Initializes the random number generator.
 * @return none.
 */
extern void mb_srand
( 
    unsigned int seed /**< seed number */
);
/**
 * @return a random number between 0 and mb_rand_max().
 */
extern int mb_rand( void );
/**
 * @return the value of the maximum random number that can be returned by
 * mb_rand().
 */
extern int mb_rand_max( void );
/**
 * @return the absolute value of x.
 */
extern float mb_fabsf
( 
    float x /**< */
);
/**
 * @return the Arc Cosine of x.
 */
extern float mb_acosf
( 
    float x /**< */
);
/**
 * @return the Arc Sine of x.
 */
extern float mb_asinf
( 
    float x  /**< */
);
/**
 * @return the Arc Tangent of x ( ]-pi/2,pi/2[ resolution ).
 */
extern float mb_atanf
( 
    float x  /**< */
);
/**
 * @return the Arc Tangent of (y / x) for ]-pi,pi] / {-pi/2,pi/2} resolution.
 */
extern float mb_atan2f
( 
    float y, /**< */ 
    float x  /**< */ 
 );
/**
 * @return the Cosine of x.
 */
extern float mb_cosf
( 
    float x  /**< */
);
/**
 * @return the Sine of x.
 */
extern float mb_sinf
( 
    float x  /**< */
);
/**
 * @return the Tangent of x.
 */
extern float mb_tanf
( 
    float x  /**< */
);
/**
 * @return the Exponential of x.
 */
extern float mb_expf
( 
    float x  /**< */
);
/**
 * @return the Natural Logarithm of x.
 */
extern float mb_logf
( 
    float x  /**< */
);
/**
 * @return the x raised to the power of y.
 */
extern float mb_powf
( 
    float x, /**< */
    float y  /**< */
);
/**
 * @return the square root of x.
 */
extern float mb_sqrtf
( 
    float x  /**< */
);
/**
 * @return the largest integer smaller than x.
 */
extern float mb_floorf
( 
    float x  /**< */
);
/**
 * @return the smallest integer larger than x.
 */
extern float mb_ceilf
( 
    float x  /**< */
);
/**
 * @return the reminder of x / y (double version).
 */
extern double mb_fmod
( 
    double x,  /**< */
    double y   /**< */
);
/**
 * @return the reminder of x / y (float version).
 */
extern float mb_fmodf
( 
    float x, /**< */
    float y  /**< */
);
/**
 * @return non zero if x is not a number, 0 otherwise.
 */
extern int mb_isnan
( 
    double x /**< */
);
/**
 * @return non zero if x is a finite number, 0 otherwise.
 */
extern int mb_finite
( 
    double x  /**< */
);
/** @} */
/*
 * ======================= Socket API ===========================================
 */
/** @defgroup socket_group Socket API
 *  @{
 * This API is used by Machblue to access the platform's socket api.
 */
/**
 * Creates a new communication socket.
 * @return MB_SCCESS and updates "s" on success or MB_FAILURE on failure.
 */
extern mb_error_t mb_socket_create
( 
    mb_socket_t      *s,           /**< pointer to socket to create */
    mb_socket_type_t  socket_type  /**< socket type to create */
);
/**
 * Deletes a new communication socket.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_socket_delete
( 
    mb_socket_t s  /**< socket to delete */
);
/**
 * Connects a stream socket to a remote host.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_socket_connect
( 
    mb_socket_t      s,        /**< socket to connect */
    const mb_char_t *hostname, /**< tcp/ip hostname of the host to connect to */
    unsigned int     port      /**< tcp/ip port to connect to */ 
);
/**
 * Disconnects a stream socket from a remote host. It is legal
 * for the client to disconnect a socket already disconnected by the
 * server (and vice-versa).
 *
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_socket_disconnect
( 
    mb_socket_t s  /**< socket to disconnect */
);
/**
 * Polls a socket for a given event.
 * @return MB_SUCCESS if the event condition polled for is current, MB_FAILURE otherwise.
 */
extern mb_error_t mb_socket_poll
( 
    mb_socket_t       s,    /**< socket to poll */ 
    mb_socket_event_t event /**< event to poll for */
);
/**
 * Sends data over a connected stream socket.
 * @return the amount of data sent on success and a strcitly negative number 
 * on failure.
 */
extern mb_ssize_t mb_socket_send
( 
    mb_socket_t  s,      /**< socket to send data on */
    const void  *msg,    /**< message to  send */
    mb_size_t    length  /**< size of the message to send in bytes */
);
/**
 * Receives data from a connected stream socket.
 * @return the amount of data read on success and a strcitly negative number 
 * on failure.
 */
extern mb_ssize_t mb_socket_recv
( 
    mb_socket_t  s,     /**< socket to receive data from */
    void        *buf,   /**< buffer to receive data in */
    mb_size_t    length /**< length in bytes of buffer */
);
/** @} */
/*
 * ======================= File API ===========================================
 */
/** @defgroup file_group File API
 *  @{
 * This API is used by Machblue to access the platform's file api.
 */
/**
 * Opens a file.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_file_open
( 
    mb_file_t       *file,  /**< pointer to file handle to store handle of newly opened file */
    const mb_char_t *path,  /**< path of the file to open */
    const mb_char_t *mode   /**< mode in which the file should be open: "r" for read only,
                                 "w" for write only, "rw" for read/write access and "a" for
                                 append mode. */
);
/**
 * Closes a file.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_file_close
( 
    mb_file_t f /**< file handle to close */
);
/**
 * Reads data from a file.
 * @return ther number of byte actually read.
 */
extern mb_size_t mb_file_read
( 
    mb_file_t  f,     /**< file to read data from */
    void      *ptr,   /**< pointer to read data into */
    mb_size_t  count  /**< number of bytes to read */
);
/**
 * Writes data to a file.
 * @return ther number of byte actually written.
 */
extern mb_size_t mb_file_write
( 
    mb_file_t   f,     /**< file to write data to */ 
    const void *ptr,   /**< pointer to data to write */ 
    mb_size_t   count  /**< number of bytes to write */
);
/**
 * Removes a file from the file system.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_file_remove
( 
    const mb_char_t *pathname /**< pathname of the file to remove */
);
/**
 * Gets the statistics of a file.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_file_stats
( 
    const mb_char_t *pathname, /**< pathname of the file to stat */
    mb_file_stats_t *stats     /**< user provided mb_file_stats_t structure used to store 
                                    requested file statistics */
);
/** @} */
/*
 * ======================= Directory API ===========================================
 */
/** @defgroup directory_group Directory API
 *  @{
 * This API is used by Machblue to access the platform's directory api.
 */
/**
 * Opens a file.
 * @return MB_SUCCESS on success, MB_NOT_A_DIRECTORY if the requested name 
 * is not a directory otherwise returns MB_FAILURE.
 */
extern mb_error_t mb_dir_open
( 
    mb_dir_t        *dir,  /**< pointer to directory handle to store handle of newly 
                                opened directory */
    const mb_char_t *name  /**< name of the directory to open */
);
/**
 * Closes a directory.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_dir_close
( 
    mb_dir_t dir  /**< directory to close */
);
/**
 * Gets the first entry of a directory. mb_dir_entry_next may called
 * to get the next entries of the directory.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_dir_entry_first
( 
    mb_dir_t        dir,   /**< directory to query */
    mb_dir_entry_t *entry  /**< pointer to directory entry to update */
);
/**
 * Gets the next entry of a directory. mb_dir_entry_first should be called
 * to get the first entry of the directory.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_dir_entry_next
( 
    mb_dir_t        dir,   /**< directory to query */
    mb_dir_entry_t *entry  /**< pointer to directory entry to update */
);
/**
 * Removes a directory from the file system.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_dir_remove
( 
    const mb_char_t *pathname  /**< absolute pathname of the directory to remove */
);
/**
 * Creates a new directory in the file system.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_dir_create
( 
    const mb_char_t *pathname  /**< absolute pathname of the directory to create */
);
/** @} */
/*
 * ======================= Surface API ===========================================
 */
/** @defgroup surface_group Surface API
 *  @{
 * This API is used by Machblue to access the platform's surface api.
 */
/**
 * Creates a new surface.
 * @return MB_SUCCESS and updates "surface" on success, MB_FAILURE otherwise.
 */
extern mb_error_t mb_surface_create
( 
    mb_surface_t      *surface,  /**< pointer to surface to create */
    int                width,    /**< width of the surface to create */
    int                height,   /**< height of the surface to create */
    mb_pixel_format_t  format    /**< pixel format of the surface to create */
);
/**
 * Deletes a surface.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_surface_delete
( 
    mb_surface_t surface  /**< surface to delete */
);
/**
 * Computes the amount of memory that would be required to create a surface
 * with the provided attributes. size_req is updated with the amount of memory 
 * required in case of success.
 * @return MB_SUCCESS and MB_FAILURE on failure.
 */
extern mb_error_t mb_surface_requirement_get
( 
    int               width,    /**< width of the surface to estimate */
    int               height,   /**< height of the surface to estimate */
    mb_pixel_format_t format,   /**< pixel format of the surface to estimate */ 
    mb_size_t         *size_req /**< pointer to location to store size requirements */
);
/**
 * Queries the attributes of a surface.
 * @return MB_SUCCESS and MB_FAILURE on failure.
 */
extern mb_error_t mb_surface_attributes_get
( 
    mb_surface_t      surface,   /**< surface to query */
    int               *width,    /**< pointer to location to store the width of 
                                      the surface */
    int               *height,   /**< pointer to location to store the height of 
                                      the surface */
    mb_pixel_format_t *format    /**< pointer to location to store the pixel format 
                                      of the surface */ 
);
/**
 * Clears a surface.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_surface_clear
( 
    mb_surface_t  surface,  /**< surface to clear */
    mb_rect_t    *rect,     /**< rectangle area to clear */
    unsigned int  color     /**< color in surface color format */
);
/**
 * Locks a surface.
 * @return MB_SUCCESS and updates locked_ptr on success and MB_FAILURE on failure. 
 * The pitch value is updated in case of success. 
 */
extern mb_error_t mb_surface_lock
( 
    mb_surface_t   surface,   /**< surface to lock */
    int           *pitch,     /**< pointer to int to store store surface pitch */
    void         **locked_ptr /**< pointer to the location to store pointer to the 
                                   locked surface buffer */
);
/**
 * Unlocks a surface.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_surface_unlock
( 
    mb_surface_t surface  /**< surface to unlock */
);
/**
 * Blits a surface into another surface.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_surface_blit
( 
    mb_surface_t      dest_surface, /**< destination surface */
    mb_rect_t        *dest_rect,    /**< destination rectangle area to blit to */ 
    mb_surface_t      src_surface,  /**< source surface */
    mb_rect_t        *src_rect,     /**< source rectangle area to blit from */ 
    mb_blit_option_t  options       /**< blit options */ 
);
/** @} */
/*
 * ======================= Font API ===========================================
 */
/** @defgroup font_group Font API
 *  @{
 * This API is used by Machblue to access the platform's font api.
 */
/**
 * Creates a new font object.
 * @return MB_SUCCESS and updates "font" on success, MB_FAILURE othrewise.
 */
extern mb_error_t mb_font_create
( 
    mb_font_t       *font,       /**< pointer to font to create */
    const mb_char_t *font_name,  /**< name of the font to create */
    mb_font_style_t  style,      /**< style of the font to create */
    int              size        /**< size of the font to create */
);
/**
 * Deletes an existing font object.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_font_delete
( 
    mb_font_t font  /**< font object to delete */
);
/**
 * Sets a new font size to the font object.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_font_size_set
( 
    mb_font_t font,     /**< font object to modify */
    int       new_size  /**< new size to set */
);
/**
 * Gets a font object attributes.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_font_attributes_get
( 
    mb_font_t  font,      /**< font object to query */
    int       *size,      /**< pointer to int to store font size */
    int       *ascender,  /**< pointer to int to store font ascender */
    int       *spacing    /**< pointer to int to store font spacing */
);
/** @} */
/*
 * ======================= Text Drawing API ===========================================
 */
/** @defgroup text_group Text Drawing API
 *  @{
 * This API is used by Machblue to access the platform's text drawing api.
 */
/**
 * Gets a text extent (bounds).
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_text_bounds_get
( 
    const mb_char_t *text,    /**< text to evaluate */
    int              length,  /**< length in characters of the text to evaluate */
    mb_font_t        font,    /**< font to use for the extent calculation */
    mb_rect_t       *bounds   /**< pointer to mb_rect_t used to store calculated extent */ 
);
/**
 * Draws a text into a surface.
 * @return MB_SUCCESS on success and MB_FAILURE on failure.
 */
extern mb_error_t mb_text_draw
( 
    const mb_char_t   *text,                   /**< text to draw */
    int                length,                 /**< length in characters of the text to draw */
    mb_surface_t       surface,                /**< destination surface to draw text to */
    mb_font_t          font,                   /**< font to draw text with */
    mb_point_t        *baseline_anchor_point,  /**< anchor point to draw text at (relative to surface) */
    mb_rect_t         *clipping_rect,          /**< text clipping rectangle (relative to surface) */
    unsigned int       color                   /**< color of the text to draw in native surface format */  
);
/** @} */
/*
 * ======================= PCM engine API ===========================================
 */
/** @defgroup pcm_group PCM engine API
 *  @{
 * This API is used by Machblue to access the platform's pcm engine api.
 */
/**
 * Opens device pcm engine for playback.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_pcm_engine_open
( 
    mb_pcm_engine_t *pcm_engine   /**< pointer to pcm engine handle to store handle 
                                       of newly opened pcm engine */
);
/**
 * Closes PCM engine.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_pcm_engine_close
( 
    mb_pcm_engine_t pcm_engine  /**< PCM engine to close */
);
/**
 * Sets PCM engine format.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_pcm_engine_format_set
( 
    mb_pcm_engine_t  pcm_engine,   /**< pcm engine to configure */ 
    mb_pcm_format_t  format,       /**< pcm format requested */
    unsigned long    sample_rate,  /**< pcm sample rate requested in Hz */
    int              n_channels    /**< number of channels requested (1 for mono, 
                                        2 for stereo, etc.) */
);
/**
 * Plays a sample buffer on a PCM engine.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_pcm_engine_play
( 
    mb_pcm_engine_t    pcm_engine,     /**< pcm engine to play samples on */ 
    const void        *sample_buffer,  /**< sample buffer to play */
    int                n_samples,      /**< number of samples to play */
    mb_pcm_callback_f *callback_f,     /**< callback function to invoke when playback is over */
    void              *cb_client_data  /**< callback function client data */
);
/** @} */
/*
 * ======================= Kernel Panic API ===========================================
 */
/** @defgroup kernel_panic_group Kernel Panic API
 *  @{
 * This API is used by Machblue to access the platform's kernel panic api.
 */
/**
 * Invokes by Machblue when an unrecoverable error has been encountered.
 * @return none.
 */
extern void mb_panic
( 
    const mb_char_t *str /**< panic string to display before aborting */
);
/** @} */
/*
 * ======================= System Time API ===========================================
 */
/** @defgroup system_time_group System Time API
 *  @{
 * This API is used by Machblue to access the platform's system time api.
 */
/**
 * Gets the current system time (UTC).
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_system_time_get
( 
    mb_system_time_t *system_time   /**< pointer to mb_system_time_t structure to update */ 
);
/**
 * Gets the system time zone.
 * @return MB_SUCCESS on success, MB_FAILURE on failure.
 */
extern mb_error_t mb_timezone_get
( 
    mb_timezone_t *timezone   /**< pointer to mb_timezone_t structure to update */ 
);
/** @} */
#ifdef __cplusplus
}      /* extern "C" */  
#endif /* __cplusplus */
#endif /* _MACHBLUE_PORTING_CORE_H_ */

						