csyn.h

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

// CSYN_SIGNAL_TYPE_SAMPLE_RATE,<br>
// CSYN_SIGNAL_TYPE_HALF_LIFE,<br>
// CSYN_SIGNAL_TYPE_TIME,<br>
// and CSYN_SIGNAL_TYPE_SVF_FREQ.
CSynErr    CSyn_SetPortSignalType( CSynContext context, CSynToken unit, CSynName portName,
                     uint32 partNum, CSyn_SignalType signalType );
// Return value set by CSyn_SetPortSignalType().
int32      CSyn_GetPortSignalType( CSynContext context, CSynToken unit, CSynName portName, uint32 partNum );

// Set the value of a port at the specified time.
CSynErr    CSyn_SetPortAt( CSynContext context, int32 tick, CSynToken unit, CSynName port,
                       uint32 partNum, double value );

// Set the value of a port. The value will be converted to internal values based
// on the port's signalType. Only ports of type CSYN_PORT_TYPE_INPUT and CSYN_PORT_TYPE_VARIABLE
// can be set using this function.
CSynErr    CSyn_SetPort( CSynContext context, CSynToken unit, CSynName port, uint32 partNum, double value );

// Write the current value of a port to the address specified by valuePtr.
// The value will be converted to human range based on the port's signalType.
CSynErr    CSyn_ReadPort( CSynContext context, CSynToken unit, CSynName port, uint32 partNum, double *valuePtr );

// CSyn_GetPort() differs from CSyn_ReadPort() in that it does not use a pointer to return the value.
// This is useful for calling from Java which does not like passing pointers.
double     CSyn_GetPort( CSynContext context, CSynToken unit, CSynName port, uint32 partNum );

// Returns the total number of frames processed on this data queue.
// Port must be either an envelope or a sample data port.
CSynErr     CSyn_ReadPortFrames( CSynContext context, CSynToken unit, CSynName port, uint32 partNum, int *valuePtr  );

// CSyn_GetPortFrames() differs from CSyn_ReadPortFrames() in that it does not use a pointer to return the value.
// This is useful for calling from Java which does not like passing pointers.
// Returns negative one on error which is ambiguous.
int     CSyn_GetPortFrames( CSynContext context, CSynToken unit, CSynName port, uint32 partNum );

// Return number of parts that a Port has, or a negative error.
// For example, CSYN_UNIT_Line_Out's input port has two parts numbered 0 and 1.
CSynErr      CSyn_GetNumParts( CSynContext context, CSynToken unit, CSynName portName );

// </group>

/************************************************************************************/
// <summary>Digital Audio Samples</summary>
// In order to play digital audio sample data, it must be copied to an internal
// JSyn resource called a "Sample". Samples can have either 1 or 2 channels.
// A "frame" is one number for a mono sample, and two numbers for a stereo Sample.
// A sample could be played using a sample reader such as CSYN_UNIT_Sample_Read16V1.
// Sample data can only be played sequentially from one frame to the next.
// <group name=samples>

// Create a sample resource with the given number of frames and channels. The value of
// numFrames must be positive and is limited by the amount of available memory.
// The parameter numChannels must be 1 or 2.
// Returns a negative number on error, or a token that can then be used with other sample
// related functions.
CSynToken  CSyn_CreateSample( CSynContext context, uint32 numFrames, uint32 numChannels );

// Write 16 bit data from the application memory space into the internal JSyn Sample memory.
// The parameter startFrame is the first frame in the Sample that will be written.
CSynErr    CSyn_WriteSample( CSynContext context, CSynToken sample, uint32 startFrame, short *address, uint32 numFrames );

// Read 16 bit data from the internal JSyn Sample memory to the application memory space.
// The parameter startFrame is the first frame in the Sample that will be read.
CSynErr    CSyn_ReadSample( CSynContext context, CSynToken sample, uint32 startFrame, short *address, uint32 numFrames );
// </group>

/************************************************************************************/
// <summary>Envelopes</summary>
// Envelopes describe a contour using a series of frames.
// Each frames consists of a duration, and a value. The duration is the length
// of time it takes to go from the previous value to the new frames value.
// Envelopes can be played using the unit CSYN_UNIT_Envelope_Linear.
// Envelope data can only be played sequentially from one frame to the next.
// <group name=envelopes>

// Create an envelope resource with the given number of frames and channels. The value of
// numFrames must be positive and is limited by the amount of available memory.
CSynToken  CSyn_CreateEnvelope( CSynContext context, uint32 numFrames );

// Write an array of envelope frames from the application memory space into the internal JSyn Sample memory.
// The parameter startFrame is the first frame in the Envelope that will be written.
CSynErr    CSyn_WriteEnvelope( CSynContext context, CSynToken env, uint32 startFrame,
                               EnvelopeFrame frames[], uint32 numFrames );

// Read an array of envelope frames from the internal JSyn Sample memory into the application memory space.
// The parameter startFrame is the first frame in the Envelope that will be read.
CSynErr    CSyn_ReadEnvelope( CSynContext context, CSynToken env, uint32 startFrame,
                              EnvelopeFrame frames[], uint32 numFrames );
// </group>

/************************************************************************************/
// <summary>Queuing Sample and Envelope Data</summary>
// Sample and envelope data is played by queuing blocks of data to a player.
// All of the typical scenarios, such as attack-sustain-release, can be implemented
// using queues.
//
// By using the flag CSYN_F_LOOP_IF_LAST one can request that the last block of data
// submitted to the queue keep looping until the queue is cleared, or new data is queued.
//
// The flag CSYN_F_AUTO_STOP requests that the player unit stop executing if the queue
// runs out of data. This can be used to save CPU time by turning off a sound when
// the amplitude envelope or a sample comes to an end.
//
// The portName is typically CSYN_PORT_Data.
// <group name=queues>

// Clear all blocks from the queue. Stop the current block and freeze the output
// of the player at the current level.
CSynErr    CSyn_ClearDataQueue( CSynContext context, CSynToken unit, CSynName portName );

// Clear all blocks from the queue at the specified time.
CSynErr    CSyn_ClearDataQueueAt( CSynContext context, int32 tick, CSynToken unit, CSynName portName );

// Add sample or envelope data to the end of the queue. 
CSynErr    CSyn_QueueData( CSynContext context, CSynToken unit, CSynName portName, CSynToken sampleOrEnvelope,
                           uint32 startFrame, uint32 numFrames, uint32 flags );

// Add data to the queue at the specified time.
CSynErr    CSyn_QueueDataAt( CSynContext context, uint32 ticks, CSynToken unit, CSynName portName, CSynToken sampleOrEnvelope,
                           uint32 startFrame, uint32 numFrames, uint32 flags );

// </group>

/************************************************************************************/
// <summary>Tables</summary>
// A Table is a JSyn resource that contains an array of floating point values.
// The values can be accessed in any order, known as "random access".

// The table can be used as a function lookup table or "wave shaper" using
// the CSYN_UNIT_Table_Lookup unit, or as a repeating waveform using the CSYN_UNIT_Osc_Table unit,
// <group name=tables>

// Create a table resource with the given number of values.
// The parameter numValues must be positive and is limited by the amount of available memory.
CSynToken  CSyn_CreateTable( CSynContext context, uint32 numValues );

// Write 16 bit data from the application memory space into the internal JSyn Table memory.
// The parameter startIndex is the first location in the Table that will be written.
// The 16 bit values will be considered as signed fixed point values and will be translated
// to floating point values before being written to the table.
// <srcblock>
// tableValue[i+startIndex] = address[i] / 32768.0
// </srcblock>
CSynErr    CSyn_WriteTable( CSynContext context, CSynToken table, uint32 startIndex, int16 *address, uint32 numValues );

// Write floating data from the application memory space directly into the internal JSyn Table memory.
// The parameter startIndex is the first location in the Table that will be written.
// The values will not be scaled.
CSynErr    CSyn_WriteTableDoubles( CSynContext context, CSynToken table, uint32 startIndex,
                                   double *address, uint32 numValues );

// Associate a Table with a unit generator. Use this if you want, for example, a table oscillator
// to play a particular waveform.
// The portName is typically CSYN_PORT_Table.
CSynErr    CSyn_UseTable( CSynContext context, CSynToken unit, CSynName portName, uint32 partNum, CSynToken table );

// </group>

/************************************************************************************/
// <summary>Time</summary>
// These calls all relate to time. Time in JSyn is measured in "ticks" which occur every
// sixty four frames. Thus if the frame rate is 44100 Hz, then the tick rate is approximately 689 Hz.
//
// The tick and frame values are unsigned integers. At a rate of 689 ticks per second,
// the tick counter will wrap around every 72 days. 
// This means that you cannot pass a time value to CSyn_SetPort() or other time stamped functions
// that is more than 36 days in the future.
// This should only affect certain types of applications.
//
// Also it is important to use the proper technique when comparing two time values.
// To simplify this process, we have provided two macros CSYN_LATER(t1,t2) and CSYN_EARLIER(t1,t2)
// which are implemented as follows:
// <srcblock>
// #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 ? */
// </srcblock>
// This technique will even work when the clock is wrapping around at the 72 day mark.

// <group name=time>

// Return the number of frames that have been calculated sine the engine was started.
uint32     CSyn_GetFrameCount( CSynContext context );

// Return the number of ticks elapsed since the engine was started.
uint32     CSyn_GetTickCount( CSynContext context );

// Returns the number of frames in a tick. Currently this is 64.
uint32     CSyn_GetFramesPerTick( CSynContext context );

// Returns the number of frames per second as specified in CSyn_StartEngine().
double     CSyn_GetFrameRate( CSynContext context );

// Returns the number of ticks per second.
// To calculate the number of ticks in 5.3 seconds, do this:
// <srcblock>
// numTicks = 5.3 * CSyn_GetTickRate();
// </srcblock>
double     CSyn_GetTickRate( CSynContext context );

// Do not return until the internal JSyn timer reaches the specified tick.
// This is the routine that should be used for scheduling musical events.
CSynErr    CSyn_SleepUntilTick( CSynContext context, int32 tick );

// Sleep for the specified number of ticks starting from now.
// Do NOT use this routine for scheduling musical events.
// It is just a convenience routine for testing.
CSynErr    CSyn_SleepForTicks( CSynContext context, int32 ticks );

// Start a timer that can be used for benchmarking a non-real time process.
CSynErr    CSyn_StartBenchTimer( CSynContext context  );

// Stop the benckmark timer.
CSynErr    CSyn_StopBenchTimer( CSynContext context  );

// Return the current time of the benchmark timer. Time is in seconds.
double     CSyn_GetBenchTimer( CSynContext context  );

// </group>

/************************************************************************************/
/* Special routines used to glue to Java via JDirect. */

long       CSyn_ErrorCodeToTextJava( int32 errorCode, char *targetText, int32 textSize );

CSynErr    CSyn_WriteEnvelopeJava( CSynContext context, CSynToken envelope, uint32 startFrame, uint32 numFrames,
                            EnvelopeFrame *data, uint32 startIndex, uint32 dataLength );
CSynErr    CSyn_ReadEnvelopeJava( CSynContext context, CSynToken envelope, uint32 startFrame, uint32 numFrames,
                            EnvelopeFrame *data, uint32 startIndex, uint32 dataLength );

CSynErr    CSyn_WriteSampleJava( CSynContext context, CSynToken sample, uint32 startFrame, uint32 numFrames,
                            int16 *data, uint32 startIndex, uint32 dataLength );
CSynErr    CSyn_ReadSampleJava( CSynContext context, CSynToken sample, uint32 startFrame, uint32 numFrames,
                            int16 *data, uint32 startIndex, uint32 dataLength );

CSynErr    CSyn_WriteTableJava( CSynContext context, CSynToken table, uint32 startFrame, uint32 numFrames,
                            int16 *data, uint32 startIndex, uint32 dataLength );
CSynErr    CSyn_WriteTableDoublesJava( CSynContext context, CSynToken table, uint32 startFrame, uint32 numFrames,
                            double *data, uint32 startIndex, uint32 dataLength );

/* Just for internal debugging. */
int32  CSyn_Debug( CSynContext context, int32 id, int32 data );

#ifdef __cplusplus
}
#endif

#endif /*  _CSYN_H  */