csyn.h

游戏编程精粹2第六章源码

	CSYN_WARN_NOT_CONNECTED,
/* Add new errors before this counter. */
	CSYN_NUM_WARNINGS
};

/* Java base in Synth.java starts at -200 */
#define CSYN_ERR_BASE (-100L)
enum CSyn_Errors  /* NOTE - order must match CSyn_ErrorText in cs_errs.c! */
{
	CSYN_ERR_NONE = 0,
	CSYN_ERR_INVALID_TOKEN_TYPE = CSYN_ERR_BASE,
	CSYN_ERR_INVALID_PORT_TYPE,
	CSYN_ERR_INVALID_TOKEN,
	CSYN_ERR_INVALID_RATE,
	CSYN_ERR_INVALID_PARTNUM,
	CSYN_ERR_INVALID_PRIORITY,
	CSYN_ERR_INVALID_SIGNAL_TYPE,
	CSYN_ERR_INVALID_SIGNAL_SIGN,
	CSYN_ERR_INVALID_CONNECTION,
	CSYN_ERR_INVALID_FLAG,
	CSYN_ERR_INVALID_DATA_TYPE,
	CSYN_ERR_OUT_OF_MEMORY,
	CSYN_ERR_TOO_MANY_TOKENS,
	CSYN_ERR_NOT_FOUND,
	CSYN_ERR_NOT_SETTABLE,
	CSYN_ERR_OUTPUT_FILE,
	CSYN_ERR_OUT_OF_RANGE,
	CSYN_ERR_HOST_INIT,
	CSYN_ERR_NOT_CONNECTED,  /* Depracated, now CSYN_WARN_NOT_CONNECTED used instead. */
	CSYN_ERR_BAD_CONNECTION,
	CSYN_ERR_MUTEX_FAILED,
	CSYN_ERR_INTERNAL_1,
	CSYN_ERR_RESTART,
	CSYN_ERR_EXPIRED,
	CSYN_ERR_INCIRCUIT,
	CSYN_ERR_RATE_MISMATCH,
	CSYN_ERR_NOT_SUPPORTED,
	CSYN_ERR_NOT_INIT,
	CSYN_ERR_INVALID_PORT_INDEX,
	CSYN_ERR_F2B_FIFO_FULL,
	CSYN_ERR_INVALID_F2B_COMMAND,
	CSYN_ERR_INVALID_B2F_COMMAND,
	CSYN_ERR_ALREADY_STARTED,
	CSYN_ERR_LINKED_LIST,
	CSYN_ERR_NUMCHANNELS_MISMATCH,
	CSYN_ERR_NOT_STARTED,
	CSYN_ERR_EMPTY_CIRCUIT,
	CSYN_ERR_INVALID_CONTEXT,
	CSYN_ERR_CONTEXT_MISMATCH,
	CSYN_ERR_INVALID_DEVICE_ID,
/* Add new errors before this counter. */
/* Don't forget to update CSyn_ErrorText in cs_errs.c! */
	CSYN_NUM_ERRORS
};

/* Assign all flags sequentially without overlap to reduce misuse. */
/* Note: these flag values must match Java declarations! */
/* Flags for CSyn_StartEngine() */
#define CSYN_F_OUT_TO_FILE       (1<<0)
#define CSYN_F_OUT_TO_PLOT       (1<<1)
#define CSYN_F_NON_REAL_TIME     (1<<2)
/* Flags for CSyn_QueueData() */
#define CSYN_F_LOOP_IF_LAST      (1<<3)
#define CSYN_F_AUTO_STOP         (1<<4)
/* Control I/O options */
#define CSYN_F_ENABLE_INPUT      (1<<5)
#define CSYN_F_DISABLE_OUTPUT    (1<<6)
/* More queue control. */
#define CSYN_F_SKIP_IF_OTHERS    (1<<7)

/*************************************************************/
/***********  Macros *****************************************/
/*************************************************************/

#define CSYN_LATER(t1,t2)    ( ( (int) ((t1) - (t2)) ) > 0 )  // is t1 later than t2 ?
#define CSYN_EARLIER(t1,t2)  ( ( (int) ((t1) - (t2)) ) < 0 )  // is t1 earlier than t2 ?

#ifdef __cplusplus
extern "C" {
#endif

/*************************************************************/
/***********  Function Prototypes  ***************************/
/*************************************************************/

	
/************************************************************************************/
// <summary>Device Management</summary>
// These routines are primarily used to access PortAudio device queries from Java.
// <group name=admin>

int32 CSyn_GetMaxInputChannels( int32 devID );
int32 CSyn_GetMaxOutputChannels( int32 devID );
int32 CSyn_DeviceIDToNameJava( int32 devID, char *targetText, int32 textSize );

/************************************************************************************/
// <summary>Library Management</summary>
// These routines are used for initializing and terminating the CSyn library.
// <group name=admin>


CSynContext CSyn_CreateContext( void );
void       CSyn_DeleteContext( CSynContext context );

// Initialize the Library
CSynErr    CSyn_Initialize( CSynContext context );
// Calls CSyn_Stop() just in case not already stopped. Deletes allocated resources.
CSynErr    CSyn_Terminate( CSynContext context );

// Start running the synthesis process. Open access to the audio device.
CSynErr    CSyn_Start( CSynContext context, uint32 flags, double frameRate );

// Start running the synthesis process. Open access to the audio device.
// Extended call that allows specification of PortAudio options.
// Because the device IDs are passed explicitly, the flags
// Synth.FLAG_ENABLE_INPUT and Synth.FLAG_DISABLE_OUTPUT are ignored.

CSynErr    CSyn_StartDevices( CSynContext context, uint32 flags, double frameRate,
				PaDeviceID inputDevice,
				int numInputChannels,
				PaDeviceID outputDevice,
				int numOutputChannels
				);

// Stop the synthesis process.
CSynErr    CSyn_Stop( CSynContext context );

// Calls CSyn_Initialize() and CSyn_Start()
CSynErr    CSyn_StartEngine( CSynContext context, uint32 flags, double frameRate );

// Calls CSyn_Terminate()
CSynErr    CSyn_StopEngine( CSynContext context );

const char *CSyn_ErrorCodeToText( CSynErr errorCode );
CSynErr    CSyn_CheckEngineErrors( CSynContext context );

double     CSyn_GetUsage( CSynContext context );
int32      CSyn_GetVersion( void );
int32      CSyn_GetExpirationDate( void );  /* 0 if licensed version, or number like 19970831 */
int32      CSyn_GetObjectCount( CSynContext context );

int32      CSyn_Debug( CSynContext context, int32 id, int32 data );
#define CSYN_DEBUG_REPORT     (1)
#define CSYN_DEBUG_THREAD     (2)
#define CSYN_RESERVED_3       (3)
#define CSYN_RESERVED_4       (4)
#define CSYN_DEBUG_GET_ALLOCS (5)
#define CSYN_DEBUG_INTERNAL   (6)

// Set flags to control printed messages for debugging and tracing code.
void       CSyn_SetTrace( CSynContext context, uint32 mask );
uint32     CSyn_GetTrace( CSynContext context );

#define CSYN_TRACE_SILENT   (0)
#define CSYN_TRACE_TERSE    (1<<0)
#define CSYN_TRACE_VERBOSE  (1<<1)

// </group>

/************************************************************************************/
// <summary>Unit Generator Management</summary>
// <group name=units>
CSynToken  CSyn_CreateUnit( CSynContext context, CSynName unitName, int32 rate, int32 param );

// Delete any allocated CSyn resource including units, samples, envelopes, etc.
// If the resource has outstanding references because of scheduled events,
// or by being in a queue, then the deletion will be deferred until
// all references are gone. This prevents a resource from being
// deleted while in use. Note that a connection between a unit to other
// units does not count as a reference. When a unit is finally deleted, it
// will be automatically disconnected from any connected units.
CSynErr    CSyn_Delete( CSynContext context, CSynToken token );

// Create circuit from an array of unit generators or other circuits.
// A circuit can be started and stopped like a unit generator.
// This guarantees that all of the units start together when necessary
// such as in circuits that use sample readers and writers to implement delays.
// Also the circuit will be stoppped if a unit that it contains is stopped
// because of an "AutoStop" event.
// An "AutoStop" event can optionally be triggered by the completion of an envelope
// or a sample.
//
// No flags are currently supported.
CSynErr    CSyn_CreateCircuit( CSynContext context, CSynToken *unitArray, uint32 numUnits, uint32 flags );

// Start the execution of a unit generator (or circuit) at the specified time.
// This, for example, will cause a unit like an oscillator to start producing sound.
// All units must be started for them to perform their function.
CSynErr    CSyn_StartUnitAt( CSynContext context, int32 tick, CSynToken unit );

// Start a unit (or circuit) as soon as possible.
CSynErr    CSyn_StartUnit( CSynContext context, CSynToken unit );

// Stop the execution of a unit generator (or circuit) at the specified time.
CSynErr    CSyn_StopUnitAt( CSynContext context, int32 tick, CSynToken unit );

// Stop a unit (or circuit) as soon as possible.
CSynErr    CSyn_StopUnit( CSynContext context, CSynToken unit );

// Connect the <b>output</b> of one unit to the input of another.
// This allows you to control one unit generator with the output of another.
// You could, for example, control the frequency of one oscillator
// with the output of another oscillator for a vibrato effect.
//
// The units must be of complementary types.
// You can connect an output of type CSYN_PORT_TYPE_OUTPUT to
// a port of type CSYN_PORT_TYPE_INPUT. You can also 
// You can also connect an output of type CSYN_PORT_TYPE_BUS_OUTPUT to
// a port of type CSYN_PORT_TYPE_BUS_INPUT. 
// No other connections may be made.
//
// Connecting Units will break any previous connections made to the same input port.
// When an input port is connected, CSyn_SetPort() will have no effect.
// A connection does not count as an "outstanding reference" by CSyn_Delete().
CSynErr    CSyn_ConnectUnits( CSynContext context, 
							  CSynToken srcUnit, CSynName srcPortName, int32 srcPartNum,
                              CSynToken dstUnit, CSynName dstPortName, int32 dstPartNum );

// Break a connection made by CSyn_ConnectUnits().
CSynErr    CSyn_DisconnectUnits( CSynContext context, CSynToken dstUnit, CSynName dstPortName, int32 dstPartNum );

// Set the execution priority of a unit generator. The priority determines the order
// of execution which affects the flow of data. 
// The order within a given priority is based on the order that the units were started.
// Units started first are executed first.
// The allowable priorities are: CSYN_PRIORITY_LOW, CSYN_PRIORITY_MEDIUM, and CSYN_PRIORITY_HIGH.
CSynErr    CSyn_SetPriority( CSynContext context, CSynToken unit, CSyn_PriorityLevel priority );

// Return priority set by CSyn_SetPriority().
CSynErr    CSyn_GetPriority( CSynContext context, CSynToken unit );

// </group>

/************************************************************************************/
// <summary>Ports</summary>
// <group name=ports>

// Set the signal type for a port. The signal type determines how the value specified
// using CSyn_SetPort() is converted to an internal numeric value.
// Setting the signal type allows one to specify a port value in more human values
// such as Hertz. 
// This function is generally used if you are using an arithmetic unit to control
// something like the frequency of a state variable filter. You can set the port on the
// arihtmetic unit to CSYN_SIGNAL_TYPE_SVF_FREQ and then pass Hz values.
// Acceptable values for signalType are:<br>
// CSYN_SIGNAL_TYPE_RAW_SIGNED,<br>
// CSYN_SIGNAL_TYPE_RAW_UNSIGNED,<br>
// CSYN_SIGNAL_TYPE_OSC_FREQ,<br>