sc68 main API
[api68 library documentation.]

This API provides functions to use sc68 libraries efficiently. More...

Data Structures

struct  api68_init_t
 API initialization. More...
struct  api68_music_info_t
 Music information. More...

Typedefs

typedef struct _api68_s api68_t
 API information.
typedef void * api68_disk_t
 API disk.

API control functions.



api68_tapi68_init (api68_init_t *init)
 Initialise sc68 API.
void api68_shutdown (api68_t *api)
 Shutdown sc68 API.
unsigned int api68_sampling_rate (api68_t *api, unsigned int f)
 Set/Get sampling rate.
void api68_set_share (api68_t *api, const char *path)
 Set share data path.
void api68_set_user (api68_t *api, const char *path)
 Set user data path.
const char * api68_error (void)
 Pop and return last stacked error message.
void api68_debug (const char *fmt,...)
 Display debug message.

Music control functions.



int api68_process (api68_t *api, void *buf, int n)
 Fill PCM buffer.
int api68_play (api68_t *api, int track)
 Set/Get current track.
int api68_stop (api68_t *api)
 Stop playing.
int api68_seek (api68_t *api, int time_ms)
 Set/Get current play position.
int api68_music_info (api68_t *api, api68_music_info_t *info, int track, api68_disk_t disk)
 Get disk/track information.

File functions.



int api68_verify (istream_t *is)
 Verify an sc68 disk.
int api68_verify_file (const char *filename)
 Verify an sc68 disk.
int api68_verify_mem (const void *buffer, int len)
 Verify an sc68 disk.
int api68_load (api68_t *api, istream_t *is)
 Load an sc68 disk for playing.
int api68_load_file (api68_t *api, const char *filename)
 Verify an sc68 disk.
int api68_load_mem (api68_t *api, const void *buffer, int len)
 Verify an sc68 disk.
api68_disk_t api68_load_disk (istream_t *is)
 Load an sc68 disk outside the API.
api68_disk_t api68_load_disk_file (const char *filename)
 Verify an sc68 disk.
api68_disk_t api68_disk_load_mem (const void *buffer, int len)
 Verify an sc68 disk.
int api68_open (api68_t *api, api68_disk_t disk)
 Change current disk.
void api68_close (api68_t *api)
 Close current disk.
int api68_tracks (api68_t *api)
 Get number of tracks.

Configuration functions



int api68_config_load (api68_t *api)
 Load config file.
int api68_config_save (api68_t *api)
 Save config file.
int api68_config_id (api68_t *api, const char *name)
 Get config variable idex.
int api68_config_get (api68_t *api, int idx, int *v)
 Get config variable value.
int api68_config_set (api68_t *api, int idx, int v)
 Set config variable value.
void api68_config_apply (api68_t *api)
 Apply current configuration to api.

Dynamic memory access.



void * api68_alloc (unsigned int n)
 Allocate dynamic memory.
void api68_free (void *data)
 Free dynamic memory.

Process status (as returned by api68_process() function)



#define API68_IDLE_BIT   1
 Set if no emulation pass has been runned.
#define API68_CHANGE_BIT   2
 Set when track has changed.
#define API68_LOOP_BIT   4
 Set when track has loop.
#define API68_END_BIT   5
 Set when finish with all tracks.
#define API68_IDLE   (1<<API68_IDLE_BIT)
#define API68_CHANGE   (1<<API68_CHANGE_BIT)
#define API68_LOOP   (1<<API68_LOOP_BIT)
#define API68_END   (1<<API68_END_BIT)
#define API68_MIX_OK   0
 Not really used.
#define API68_MIX_ERROR   -1
 Error.

Detailed Description

This API provides functions to use sc68 libraries efficiently.

Multi-threading issue

The API is not thread safe. Currently the 68000 emulator does not handle multi instance. Anyway the API may be used in multi-thread context as soon as you take care to play only one disk at a time.

Have a look to the xmms68 package to see how to use this API in multi-thread context.

Quick start
  #include "api68/api68.h"

  api68_init_t init68;
  api68_t * sc68 = 0;
  char buffer[512*4];

  // Clean up init structure (required).
  memset(&init68, 0, sizeof(init68));
  // Set dynamic handler (required).
  init68.alloc = malloc;
  init68.free = free;
  // Set debug message handler (optionnal).
  init68.debug = vfprintf;
  init68.debug_cookie = stderr;
  sc68 = api68_init(&init68);
  if (!sc68) goto error;

  // Load an sc68 file.
  if (api68_load_file(sc68, fname)) {
    goto error;
  }

  // Set a track (optionnal).
  api68_play(sc68, track);

  // Loop until the end of disk. You can use API68_LOOP to wait the end
  // of the track. Notice that API68_ERROR set all bits and make the loop
  // break too.
  while ( ! (api68_process(sc68, buffer, sizeof(buffer) >> 2) & API68_END)) {
    // Do something with buffer[] here.
  }

  // Stop current track (optionnal).
  api68_stop(sc68);

 error:
  // Shutdown everything (0 pointer could be sent safely).
  api68_shutdown(sc68);

Define Documentation

#define API68_IDLE_BIT   1

Set if no emulation pass has been runned.

#define API68_CHANGE_BIT   2

Set when track has changed.

#define API68_LOOP_BIT   4

Set when track has loop.

#define API68_END_BIT   5

Set when finish with all tracks.

#define API68_IDLE   (1<<API68_IDLE_BIT)
See also:
API68_IDLE_BIT
#define API68_CHANGE   (1<<API68_CHANGE_BIT)
See also:
API68_CHANGE_BIT
#define API68_LOOP   (1<<API68_LOOP_BIT)
See also:
API68_LOOP_BIT
#define API68_END   (1<<API68_END_BIT)
See also:
API68_END_BIT
#define API68_MIX_OK   0

Not really used.

#define API68_MIX_ERROR   -1

Error.


Typedef Documentation

typedef struct _api68_s api68_t

API information.

typedef void* api68_disk_t

API disk.


Function Documentation

api68_t* api68_init ( api68_init_t init  ) 

Initialise sc68 API.

Parameters:
init Initialization parameters.
Returns:
Pointer ti initialized API.
Return values:
0 Error.
Warning:
Currently only one API can be initialized.
void api68_shutdown ( api68_t api  ) 

Shutdown sc68 API.

Parameters:
api sc68 api.
Note:
It is safe to call with null api.
unsigned int api68_sampling_rate ( api68_t api,
unsigned int  f 
)

Set/Get sampling rate.

Parameters:
api sc68 api.
f New sampling rate in hz or 0 to read current.
Returns:
Sampling rate (could be diffrent from requested one).
Return values:
Error (not initialized).
void api68_set_share ( api68_t api,
const char *  path 
)

Set share data path.

Parameters:
api sc68 api.
path New shared data path.
void api68_set_user ( api68_t api,
const char *  path 
)

Set user data path.

Parameters:
api sc68 api.
path New user data path.
const char* api68_error ( void   ) 

Pop and return last stacked error message.

Returns:
Error message
Return values:
0 No stacked error message
void api68_debug ( const char *  fmt,
  ... 
)

Display debug message.

Parameters:
fmt printf() like format string.
See also:
debugmsg68()
int api68_process ( api68_t api,
void *  buf,
int  n 
)

Fill PCM buffer.

The api68_process() function fills the PCM buffer with the current music data. If the current track is finished and it is not the last the next one is automatically loaded. The function returns status value that report events that have occured during this pass.

Parameters:
api sc68 api.
buf PCM buffer (must be at leat 4*n bytes).
n Number of sample to fill.
Returns:
Process status
int api68_play ( api68_t api,
int  track 
)

Set/Get current track.

The api68_play() function get or set current track.

If track == -1 the function returns the current track or 0 if none.

Else the function will test the requested track number. If it is 0, the disk default track will be use. If the track is out of range, the function fails and returns -1 else it returns 0. To avoid multi-threading issus the track is not changed directly but a change-track event is posted. This ecvent will be processed at the next call to the api68_process() function.

Parameters:
api sc68 api.
track track number [-1:read current, 0:set disk default]
Returns:
error code or track number.
Return values:
0 Success or no current track
>0 Current track
-1 Failure.
int api68_stop ( api68_t api  ) 

Stop playing.

The api68_stop() function stop current playing track. Like the api68_play() function the api68_stop() function does not really stop the music but send a stop-event that will be processed by the next call to api68_process() function.

Parameters:
api sc68 api.
Returns:
error code
Return values:
0 Success
-1 Failure
int api68_seek ( api68_t api,
int  time_ms 
)

Set/Get current play position.

The api68_seek() functions get or set the current play position.

If time_ms == -1 the function will returns the current play position or -1 if not currently playing.

If time_ms >= 0 the function will try to seek to the given position. If time_ms is out of range the function returns -1. If time_ms is inside the current playing track the function does not seek and returns -1. Else the function change to the track which time_ms belong and returns the time position at the beginning of this track.

The returned time is always the number of millisecond since the disk has started (not the track).

Parameters:
api sc68 api.
time_ms new time position in ms (-1:read current time).
Returns:
error code
Return values:
0 Success
-1 Failure
int api68_music_info ( api68_t api,
api68_music_info_t info,
int  track,
api68_disk_t  disk 
)

Get disk/track information.

Parameters:
api sc68 api
info track/disk information structure to be filled.
track track number (-1:current/default 0:disk-info).
disk disk to get information from (0 means API disk).
Returns:
error code
Return values:
0 Success.
-1 Failure.
Warning:
API disk informations are valid as soon as the disk is loaded and must not be used after api_load() or api_close() function call. If disk was given the information are valid until the disk is freed.
int api68_verify ( istream_t is  ) 

Verify an sc68 disk.

int api68_verify_file ( const char *  filename  ) 

Verify an sc68 disk.

int api68_verify_mem ( const void *  buffer,
int  len 
)

Verify an sc68 disk.

int api68_load ( api68_t api,
istream_t is 
)

Load an sc68 disk for playing.

int api68_load_file ( api68_t api,
const char *  filename 
)

Verify an sc68 disk.

int api68_load_mem ( api68_t api,
const void *  buffer,
int  len 
)

Verify an sc68 disk.

api68_disk_t api68_load_disk ( istream_t is  ) 

Load an sc68 disk outside the API.

Free it with api68_free() function.

api68_disk_t api68_load_disk_file ( const char *  filename  ) 

Verify an sc68 disk.

api68_disk_t api68_disk_load_mem ( const void *  buffer,
int  len 
)

Verify an sc68 disk.

int api68_open ( api68_t api,
api68_disk_t  disk 
)

Change current disk.

Parameters:
api sc68 api
disk New disk (0 does a api68_close())
Returns:
error code
Return values:
0 Success, disk has been loaded.
-1 Failure, no disk has been loaded (occurs if disk was 0).
Note:
Can be safely call with null api.
Warning:
After api68_open() failure, the disk has been freed.
Beware not to use disk information after api68_close() call because the disk should have been destroyed.
void api68_close ( api68_t api  ) 

Close current disk.

Parameters:
api sc68 api
Note:
Can be safely call with null api or if no disk has been loaded.
int api68_tracks ( api68_t api  ) 

Get number of tracks.

Parameters:
api sc68 api
Returns:
Number of track
Return values:
-1 error
Note:
Could be use to check if a disk is loaded.
int api68_config_load ( api68_t api  ) 

Load config file.

Parameters:
api sc68 api
int api68_config_save ( api68_t api  ) 

Save config file.

Parameters:
api sc68 api
int api68_config_id ( api68_t api,
const char *  name 
)

Get config variable idex.

Parameters:
api sc68 api
name name of config variable
Returns:
config index
Return values:
-1 Error
int api68_config_get ( api68_t api,
int  idx,
int *  v 
)

Get config variable value.

Parameters:
api sc68 api
idx config index
v pointer to store config value
Returns:
Error code
Return values:
0 Success
-1 Failure
int api68_config_set ( api68_t api,
int  idx,
int  v 
)

Set config variable value.

Parameters:
api sc68 api
idx config index
v new config value
Returns:
Error code
Return values:
0 Success
-1 Failure
void api68_config_apply ( api68_t api  ) 

Apply current configuration to api.

Parameters:
api sc68 api
void* api68_alloc ( unsigned int  n  ) 

Allocate dynamic memory.

The api68_alloc() function calls the SC68alloc() function.

Parameters:
n Size of buffer to allocate.
Returns:
pointer to allocated memory buffer.
Return values:
0 error
See also:
SC68alloc()
void api68_free ( void *  data  ) 

Free dynamic memory.

The api68_free() function calls the SC68free() function.

Parameters:
data Previously allocated memory buffer.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Generated on Thu Sep 16 07:46:11 2010 for sc68fordevelopers by  doxygen 1.6.3