Struct csound::Csound

pub struct Csound { /* fields omitted */ }

Opaque struct representing an csound object

This is the main struct used to access the libcsound API functions. The Engine element is the inner representation of the CSOUND opaque pointer and is the object wich talk directly with the libcsound c library.

Methods

impl Csound

pub fn new() -> Csound

Create a new csound object.

This is the core of almost all operations in the csound library. A new instance of csound will created by this function, a custom callback handler will be used, This custom callback handler will be active only if the user calls some of the callbacks setting functions which receive a closure for a specific callback.

Example

 // Creates a Csound instance and use a custom callback handler
let csound = Csound::new();
// enable the message callback passing a closure to the custom callback handler
csound.message_string_callback( |mtype:u32, message:&str| {
    println!("message type: {} message content:  {}", mtype, message);
});
csound.compile_csd(csd_filename).unwrap();
csound.start();

pub fn initialize(flags: i32) -> Result<(), &'static str>

Initializes the csound library with specific flags(see: anchor text). This function is called internally by Csound::new(), so there is generally no need to use it explicitly unless you need to avoid default initilization that sets signal handlers and atexit() callbacks. Return value is Ok() on success or an error message in case of failure

pub fn set_option(&self, option: &str) -> Result<(), &'static str>

Sets a single csound option(flag).

NB: blank spaces are not allowed.

Returns

returns Ok on success or an error message in case the option is invalid.

pub fn start(&self) -> Result<(), &'static str>

Prepares Csound for performance.

Normally called after compiling a csd file or an orc file, in which case score preprocessing is performed and performance terminates when the score terminates. However, if called before compiling a csd file or an orc file, score preprocessing is not performed and "i" statements are dispatched as real-time events, the tag is ignored, and performance continues indefinitely or until ended using the API.

Example

let csound = Csound::new();
csound.compile_csd(csd_filename).unwrap();
csound.start();
...

pub fn version(&self) -> u32

Returns the version number times 1000 for example, if the current csound version is 6.12.0 this function will return 6120.

pub fn api_version(&self) -> u32

Returns the API version number times 100

pub fn stop(&self)

Stops the performance of a csound's instance Note: It is not guaranteed that Csound::perform has already stopped when this function returns.

pub fn reset(&self)

Resets all internal memory and state in preparation for a new performance. Enables external software to run successive Csound performances without reloading Csound.

pub fn compile<T>(&self, args: &[T]) -> Result<(), &'static str> where
    T: AsRef<str>, 

Compiles Csound input files (such as an orchestra and score, or CSD) as directed by the supplied command-line arguments , but does not perform them. This function cannot be called during performance, and before a repeated call, csoundReset() needs to be called.

Arguments

• args A slice containing the arguments to be passed to csound

Returns

A error message in case of failure

pub fn compile_csd<T>(&self, csd: T) -> Result<(), &'static str> where
    T: AsRef<str>, 

Compiles a Csound input file (CSD, .csd file), but does not perform it. If Csound::start is called before compile_csd, the element is ignored (but set_option can be called any number of times), the element is not pre-processed, but dispatched as real-time events; and performance continues indefinitely, or until ended by calling Csound::stop or some other logic. In this "real-time" mode, the sequence of calls should be:

let csound  = Csound::new();
csound.set_option("-an_option");
csound.set_option("-another_option");
csound.start();
csound.compile_csd(csd_filename);
while true{
    // Send realtime events
    csound.send_score_event("i 1 0 5 4.5 6.2");
    //...
    // some logic to break the loop after a performance of realtime events
}

Note: this function can be called repeatedly during performance to replace or add new instruments and events. But if csoundCompileCsd is called before csoundStart, the element is used,the section is pre-processed and dispatched normally, and performance terminates when the score terminates, or Csound::stop is called. In this "non-real-time" mode (which can still output real-time audio and handle real-time events), the sequence of calls should be:

let csound  = Csound::new();
csound.compile_csd(csd_filename);
csound.start();
while !csound.perform_ksmps() {
}

Arguments

• csd A reference to .csd file name

pub fn compile_csd_text<T>(&self, csdText: T) -> Result<(), &'static str> where
    T: AsRef<str>, 

Behaves the same way as Csound::compile_csd, except that the content of the CSD is read from a string rather than from a file. This is convenient when it is desirable to package the csd as part of an application or a multi-language piece.

Arguments

• csd_text A reference to the text to be compiled by csound

pub fn compile_orc<T>(&self, orc: T) -> Result<(), &'static str> where
    T: AsRef<str>, 

Parses and compiles the given orchestra from an ASCII string, also evaluating any global space code (i-time only) this can be called during performance to compile a new orchestra.

let csound  = Csound::new();
let orc_code = "instr 1
                a1 rand 0dbfs/4
                out a1";
csound.compile_orc(orc_code);

Arguments

• orcPath A reference to orchestra strings

pub fn compile_orc_async<T>(&self, orc: T) -> Result<(), &'static str> where
    T: AsRef<str>, 

Async version of Csound::compile_orc. The code is parsed and compiled, then placed on a queue for asynchronous merge into the running engine, and evaluation. The function returns following parsing and compilation.

Arguments

• orc A reference to an csound's orchestra definitions

pub fn eval_code<T>(&self, code: T) -> Result<f64, &'static str> where
    T: AsRef<str>, 

Parse and compile an orchestra given on a string, evaluating any global space code (i-time only).

Returns

On SUCCESS it returns a value passed to the 'return' opcode in global space. code = "i1 = 2 + 2 \n return i1 \n" retval = csound.eval_code(code)

pub fn perform(&self) -> i32

Senses input events and performs audio output.

perform until: 1. the end of score is reached (positive return value), 2. an error occurs (negative return value), or 3. performance is stopped by calling stop() from another thread (zero return value). Note that some csf file, text or score have to be compiled first and then start() must be called. In the case of zero return value, perform() can be called again to continue the stopped performance. Otherwise, Csound::reset should be called to clean up after the finished or failed performance.

pub fn perform_ksmps(&self) -> bool

Senses input events, and performs one control sample worth ksmps * number of channels * size_off::<f64> bytes of audio output.

Note that some csd file, text or score have to be compiled first and then Csound::start. Enables external software to control the execution of Csound, and to synchronize performance with audio input and output(see: Csound::read_spin_buffer, Csound::read_spout_buffer)

Returns

false during performance, and true when performance has finished. If called until it returns true, will perform an entire score.

pub fn perform_buffer(&self) -> bool

Performs Csound, sensing real-time and score events and processing one buffer's worth (-b frames) of interleaved audio. Note that some csd file, text or score have to be compiled first and then Csound::start, you could call Csound::read_output_buffer or Csound::write_input_buffer to write/read the csound's I/O buffers content. #Returns false during performance or true when performance has finished.

pub fn udp_server_start(&self, port: u32) -> Result<(), Status>

Starts the UDP server

Arguments

• port The server port number.

Returns

Ok on success or an error code on failure.

pub fn udp_server_status(&self) -> Option<u32>

Returns

The port number on which the server is running, or None if the server has not been started.

pub fn udp_server_close(&self) -> Result<(), Status>

Closes the UDP server

Returns

Ok if the running server was successfully closed, Status code otherwise.

pub fn udp_console(
    &self,
    addr: &str,
    port: u32,
    mirror: bool
) -> Result<(), Status>

Turns on the transmission of console messages

Arguments

• addr The UDP server destination address.
• port The UDP server port number.
• mirror If it is true, the messages will continue to be sent to the usual destination (see Csound::message_string_callback ) as well as to UDP.

Returns

Ok on success or an Status code if the UDP transmission could not be set up.

pub fn udp_stop_console(&self)

Stop transmitting console messages via UDP

pub fn get_sample_rate(&self) -> f64

Returns

The number of audio sample frames per second.

pub fn get_control_rate(&self) -> f64

Returns

The number of control samples per second.

pub fn get_ksmps(&self) -> u32

Returns

The number of audio sample frames per control sample.

pub fn output_channels(&self) -> u32

Returns

The number of audio output channels. Set through the nchnls header variable in the csd file.

pub fn input_channels(&self) -> u32

Returns

The number of audio input channels. Set through the nchnls_i header variable in the csd file. If this variable is not set, the value is taken from nchnls.

pub fn get_0dBFS(&self) -> f64

Returns

The 0dBFS level of the spin/spout buffers.

pub fn get_freq(&self) -> f64

Returns

The A4 frequency reference

pub fn get_current_sample_time(&self) -> usize

#Returns The current performance time in samples

pub fn get_size_myflt(&self) -> u32

Returns

The size of MYFLT in bytes.

pub fn get_debug_level(&self) -> u32

Returns

Whether Csound is set to print debug messages. sents through the DebugMsg() csouns's internal API function. Anything different to 0 means true.

pub fn set_debug_level(&self, level: i32)

Sets whether Csound prints debug messages from the DebugMsg() csouns's internal API function.

Arguments

• level The debug level to assign, anything different to 0 means true.

pub fn get_input_name(&self) -> Option<String>

Gets the csound's input source name if it has been defined otherwise, None is returned

pub fn get_output_name(&self) -> Option<String>

Gets output device name if the realtime output has been defined, Otherwise, None is returned

pub fn set_output(
    &self,
    name: &str,
    out_type: &str,
    format: &str
) -> Result<(), NulError>

Set output destination, type and format

Arguments

• name The destination/device name, for RT audio use the field CsAudioDevice::device_id. (see: Csound::get_audio_devices)
• out_type can be one of "wav","aiff", "au","raw", "paf", "svx", "nist", "voc", "ircam","w64","mat4", "mat5", "pvf","xi", "htk","sds","avr", "wavex","sd2", "flac", "caf","wve","ogg","mpc2k","rf64", or NULL (use default or realtime IO).
• format can be one of "alaw", "schar", "uchar", "float", "double", "long", "short", "ulaw", "24bit", "vorbis", or NULL (use default or realtime IO).

pub fn get_output_format(&self) -> Result<(String, String), Utf8Error>

Get output type and format.

Example

let csound = Csound::new();
let (output_type, output_format) = csound.get_output_format().unwrap();

pub fn set_input(&self, name: &str) -> Result<(), NulError>

Sets input source

Arguments

• name The source device name.

pub fn set_midi_file_input(&self, name: &str) -> Result<(), NulError>

Set MIDI file input name

pub fn set_midi_file_output(&self, name: &str) -> Result<(), NulError>

Set MIDI file output name

pub fn set_midi_input(&self, name: &str) -> Result<(), NulError>

Set MIDI input device name/number

pub fn set_midi_output(&self, name: &str) -> Result<(), NulError>

Set MIDI output device name

pub fn set_rt_audio_module(&self, name: &str) -> Result<(), NulError>

Sets the current RT audio module

pub fn get_input_buffer_size(&self) -> usize

Returns

The number of samples in Csound's input buffer.

pub fn get_output_buffer_size(&self) -> usize

Returns

The number of samples in Csound's input buffer.

pub fn get_input_buffer(&self) -> Option<BufferPtr<Writable>>

Gets the csound's input buffer.

Returns

An Option containing either the BufferPtr or None if the csound's input buffer has not been initialized. The returned BufferPtr is Writable, it means that you can modify the csound's buffer content in order to write external audio data into csound and process it.

Example

let csound = Csound::new();
csound.compile_csd("some_file_path");
csound.start();
let input_buffer_ptr = csound.get_input_buffer();
while !csound.perform_buffer() {
    // fills your buffer with audio samples that you want to pass into csound
    foo_fill_buffer(input_buffer_ptr.as_mut_slice());
    // ...
}

pub fn get_output_buffer(&self) -> Option<BufferPtr<Readable>>

Gets the csound's output buffer.

Returns

An Option containing either the BufferPtr or None if the csound's output buffer has not been initialized. The returned BufferPtr is only Readable.

Example

let csound = Csound::new();
csound.compile_csd("some_file_path");
csound.start();
let output_buffer_ptr = csound.get_output_buffer();
let mut data = vec![0f64; input_buffer_ptr.get_size()];
while !csound.perform_buffer() {
    // process the data from csound
    foo_process_buffer(output_buffer_ptr.as_slice());
}

pub fn get_spin(&self) -> Option<BufferPtr<Writable>>

Enables external software to write audio into Csound before calling perform_ksmps.

Returns

An Option containing either the BufferPtr or None if the csound's spin buffer has not been initialized. The returned BufferPtr is Writable.

Example

let csound = Csound::new();
csound.compile_csd("some_file_path");
csound.start();
let spin = csound.get_spin();
while !csound.perform_ksmps() {
    // fills the spin buffer with audio samples that you want to pass into csound
    foo_fill_buffer(spin.as_mut_slice());
    // ...
}

pub fn get_spout(&self) -> Option<BufferPtr<Readable>>

Enables external software to read audio from Csound before calling perform_ksmps.

Returns

An Option containing either the BufferPtr or None if the csound's spout buffer has not been initialized. The returned BufferPtr is only Readable.

Example

let csound = Csound::new();
csound.compile_csd("some_file_path");
csound.start();
let spout = csound.get_spout();
while !csound.perform_ksmps() {
    // Deref the spout pointer and read its content
    foo_read_buffer(&*spout);
    // ...
}

pub fn read_output_buffer(
    &self,
    output: &mut [f64]
) -> Result<usize, &'static str>

Deprecated since 0.1.5:

please use Csound::get_output_buffer object instead

Method used when you want to copy audio samples from the csound's output buffer.

Arguments

• out a reference to a mutable slice where the Csound's output buffer content will be copied. This buffer have to has enough memory for at least Csound::get_output_buffer_size, samples.

Returns

The number of samples copied into the slice on success, or an error message if the internal csound's buffer has not been initialized.

Example

let csound = Csound::new();
csound.compile_csd("some_file_path");
csound.start();
let output_buffer_length = csound.get_output_buffer_size();
let mut output_buffer = vec![0f64; output_buffer_length];
while !csound.perform_buffer() {
    csound.read_output_buffer(&mut output_buffer).unwrap();
    // ... do some stuff with the buffer
}

Deprecated

Use Csound::get_output_buffer to get a BufferPtr object.

pub fn write_input_buffer(&self, input: &[f64]) -> Result<usize, &'static str>

Deprecated since 0.1.5:

please use Csound::get_input_buffer object instead

Method used when you want to copy custom audio samples into the csound buffer to be processed.

Arguments

• input a reference to a slice with samples which will be copied to the Csound's input buffer.

Returns

The number of samples copied into the csound's input buffer or an error message if the internal csound's buffer has not been initialized.

Example

let csound = Csound::new();
csound.compile_csd("some_file_path");
csound.start();
let input_buffer_length = csound.get_input_buffer_size();
let mut input_buffer = vec![0f64; output_buffer_length];
while !csound.perform_buffer() {
    // fills your buffer with audio samples you want to pass into csound
    foo_fill_buffer(&mut input_buffer);
    csound.write_input_buffer(&input_buffer);
    // ...
}

Deprecated

Use Csound::get_input_buffer to get a BufferPtr object.

pub fn read_spout_buffer(
    &self,
    output: &mut [f64]
) -> Result<usize, &'static str>

Deprecated since 0.1.5:

please use Csound::get_spout object instead

Enables external software to read audio from Csound after calling Csound::perform_ksmps

Returns

The number of samples copied or an error message if the internal csound's buffer has not been initialized.

Example

let csound = Csound::new();
csound.compile_csd("some_file_path");
csound.start();
let spout_length = csound.get_ksmps() * csound.output_channels();
let mut spout_buffer = vec![0f64; spout_length as usize];
while !csound.perform_ksmps() {
    // fills your buffer with audio samples you want to pass into csound
    foo_fill_buffer(&mut spout_buffer);
    csound.read_spout_buffer(&spout_buffer);
    // ...
}

Deprecated

Use Csound::get_spout to get a BufferPtr object.

pub fn write_spin_buffer(&self, input: &[f64]) -> Result<usize, &'static str>

Deprecated since 0.1.5:

please use Csound::get_spin object instead

Enables external software to write audio into Csound before calling Csound::perform_ksmps Csound::get_ksmps * Csound::input_channels.

Returns

The number of samples copied or an error message if the internal csound's buffer has not been initialized.

Example

let csound = Csound::new();
csound.compile_csd("some_file_path");
csound.start();
let spin_length = csound.get_ksmps() * csound.input_channels();
let mut spin_buffer = vec![0f64; spin_length as usize];
while !csound.perform_ksmps() {
    // fills your buffer with audio samples you want to pass into csound
    foo_fill_buffer(&mut spin_buffer);
    csound.write_spin_buffer(&spin_buffer);
    // ...
}

Deprecated

Use Csound::get_spin to get a BufferPtr object.

pub fn clear_spin(&self)

Clears the spin buffer.

pub fn add_spin_sample(&self, frame: u32, channel: u32, sample: f64)

Adds the indicated sample into the audio input working buffer (spin); this only ever makes sense before calling Csound::perform_ksmps. The frame and channel must be in bounds relative to ksmps and nchnls. Note: the spin buffer needs to be cleared at every k-cycle by calling Csound::clear_spin.

pub fn set_spin_sample(&self, frame: u32, channel: u32, sample: f64)

Sets the audio input working buffer (spin) to the indicated sample. this only ever makes sense before calling Csound::perform_ksmps. The frame and channel must be in bounds relative to ksmps and nchnls.

pub fn get_spout_sample(&self, frame: u32, channel: u32) -> f64

Gets an audio sample from the spout buffer. only ever makes sense before calling Csound::perform_ksmps. The frame and channel must be in bounds relative to ksmps and nchnls. #Returns The indicated sample from the Csound audio output working buffer (spout).

pub fn set_host_implemented_audioIO(&self, state: u32, bufSize: u32)

Enable to host to handle the audio implementation. Calling this function with a non-zero 'state' value between Csound::create and the start of performance will disable all default handling of sound I/O by the Csound library, allowing the host application to use the spin,spout,input, output buffers directly.

Arguments

• state An no zero value will diseable all default handling of sound I/O in csound.
• bufSize For applications using spin / spout, this argument should be set to 0 but if bufSize is greater than zero, the buffer size (-b) in frames will be set to the integer multiple of ksmps that is nearest to the value specified.

pub fn get_audio_devices(&self) -> (Vec<CsAudioDevice>, Vec<CsAudioDevice>)

This function can be called to obtain a list of available input and output audio devices.

Returns

A tuple, being input devices the first element in the returned tuple, output devices the second one.

pub fn set_midi_module(&self, name: &str)

Sets the current MIDI IO module

pub fn set_host_implemented_midiIO(&self, state: u32)

call this function with state 1 if the host is going to implement MIDI through the callbacks

pub fn get_midi_devices(&self) -> (Vec<CsMidiDevice>, Vec<CsMidiDevice>)

This function can be called to obtain a list of available input or output midi devices.

Returns

A tuple with two vectors, beign the first one for input MIDI devices and the second one for output MIDI devices

pub fn read_score(&self, score: &str) -> Result<(), &'static str>

Reads, preprocesses, and loads a score from an ASCII string. It can be called repeatedly with the new score events being added to the currently scheduled ones.

pub fn read_score_async(&self, score: &str) -> Result<(), &'static str>

Asynchronous version of Csound::read_score

pub fn get_score_time(&self) -> f64

Returns

The current score time in seconds since the beginning of the performance.

pub fn is_score_pending(&self) -> i32

Sets whether Csound score events are performed or not. Independently of real-time MIDI events (see Csound::set_score_pending).

pub fn set_score_pending(&self, pending: i32)

Sets whether Csound score events are performed or not (real-time events will continue to be performed). Can be used by external software, such as a VST host, to turn off performance of score events (while continuing to perform real-time events), for example to mute a Csound score while working on other tracks of a piece, or to play the Csound instruments live.

pub fn get_score_offset_seconds(&self) -> f64

Gets the current score's time.

Returns

The score time beginning at which score events will actually immediately be performed (see Csound::set_score_offset_seconds).

pub fn set_score_offset_seconds(&self, offset: f64)

Csound score events prior to the specified time are not performed. And performance begins immediately at the specified time (real-time events will continue to be performed as they are received). Can be used by external software, such as a VST host, to begin score performance midway through a Csound score, for example to repeat a loop in a sequencer or to synchronize other events with the Csound score.

pub fn rewind_score(&self)

Rewinds a compiled Csound score to the time specified with Csound::set_score_offset_seconds

pub fn get_message_level(&self) -> u8

Returns

The Csound message level (from 0 to 231).

pub fn set_message_level(&self, level: u8)

Sets the Csound message level (from 0 to 231).

pub fn create_message_buffer(&self, stdout: i32)

Creates a buffer for storing messages printed by Csound. Should be called after creating a Csound instance and the buffer can be freed by calling Csound::destroy_message_buffer or it will freed when the csound instance is dropped. You will generally want to call Csound::cleanup to make sure the last messages are flushed to the message buffer before destroying Csound.

Arguments

• stdout If is non-zero, the messages are also printed to stdout and stderr (depending on the type of the message), in addition to being stored in the buffer. Note: Using the message buffer ties up the internal message callback, so Csound::message_string_callback should not be called after creating the message buffer.

pub fn destroy_message_buffer(&self)

Releases all memory used by the message buffer. If this buffer is created, the Drop method will call this function when the Csound instance were dropped.

pub fn get_first_message(&self) -> Option<String>

Returns

The first message from the buffer.

pub fn get_first_message_attr(&self) -> MessageType

Returns

The attribute parameter (MessageType) of the first message in the buffer.

pub fn pop_first_message(&self)

Removes the first message from the buffer.

pub fn get_message_count(&self) -> u32

Returns

The number of pending messages in the buffer.

pub fn list_channels(&self) -> Option<Vec<ChannelInfo>>

Requests a list of all control channels.

Returns

A vector with all control channels info or None if there are not control channels. see: ChannelInfo

pub fn get_channel_ptr<'a>(
    &'a self,
    name: &str,
    channel_type: ControlChannelType
) -> Result<ControlChannelPtr<'a>, Status>

Deprecated since 0.1.6:

please use get_input_channel or get_output_channel instead

Return a ControlChannelPtr which represent a csound's channel ptr. creating the channel first if it does not exist yet.

Arguments

• name The channel name.
• channel_type must be the bitwise OR of exactly one of the following values:

• CSOUND_CONTROL_CHANNEL control data (one MYFLT value)
• CSOUND_AUDIO_CHANNEL audio data (get_ksmps() f64 values)
• CSOUND_STRING_CHANNEL string data (f64 values with enough space to store get_channel_data_size() characters, including the NULL character at the end of the string) and at least one of these:
• CSOUND_INPUT_CHANNEL
• CSOUND_OUTPUT_CHANNEL If the channel already exists, it must match the data type (control, audio, or string), however, the input/output bits are OR'd with the new value. Note that audio and string channels can only be created after calling Compile(), because the storage size is not known until then.

Returns

The ControlChannelPtr on success or a Status code, "Not enough memory for allocating the channel" (CS_MEMORY) "The specified name or type is invalid" (CS_ERROR) or, if a channel with the same name but incompatible type already exists, the type of the existing channel.

• Note:* to find out the type of a channel without actually creating or changing it, set 'channel_type' argument to CSOUND_UNKNOWN_CHANNEL, so that the error value will be either the type of the channel, or CSOUND_ERROR if it does not exist. Operations on the channel pointer are not thread-safe by default. The host is required to take care of threadsafety by
  1. with control channels use __sync_fetch_and_add() or __sync_fetch_and_or() gcc atomic builtins to get or set a channel, if available.
  2. For string and audio channels (and controls if option 1 is not available), retrieve the channel lock with ChannelLock() and use SpinLock() and SpinUnLock() to protect access to the channel. See Top/threadsafe.c in the Csound library sources for examples. Optionally, use the channel get/set functions which are threadsafe by default.

pub fn set_channel_hints(
    &self,
    name: &str,
    hint: &ChannelHints
) -> Result<(), Status>

Set parameters hints for a control channel. These hints have no internal function but can be used by front ends to construct GUIs or to constrain values.

Returns

CS_SUCCESS on success, or CS_ERROR on failure: the channel does not exist, is not a control channel, or the specified parameters are invalid or CS_MEMORY: could not allocate memory for the channel. see: (Status)

pub fn get_channel_hints(&self, name: &str) -> Result<ChannelHints, Status>

Returns special parameters (or None if there are not any) of a control channel. Previously set with csoundSetControlChannelHints() or the chnparams opcode.

pub fn get_control_channel(&self, name: &str) -> Result<f64, &'static str>

Retrieves the value of a control channel.

Arguments

• name The channel name. An error message will be returned if the channel is not a control channel, the channel not exist or if the name is invalid.

pub fn set_control_channel(&self, name: &str, value: f64)

Sets the value of a control channel.

Arguments

• name The channel name.

pub fn read_audio_channel(&self, name: &str, output: &mut [f64])

Copies samples from an audio channel.

Arguments

• name The channel name.
• out The slice where the date contained in the internal audio channel buffer will be copied. Should contain enough memory for ksmps f64 samples.

Panic

If the buffer passed to this function doesn't have enough memory.

pub fn write_audio_channel(&self, name: &str, input: &[f64])

Writes data into an audio channel buffer. audio channel identified by name with data from slice input which should contain at least ksmps f64 samples, if not, this method will panic.

Arguments

• input The slice with data to be copied into the audio channel buffer. Could contain up to ksmps samples.

panic

This method will panic if input.len() > ksmps.

pub fn get_string_channel(&self, name: &str) -> String

Returns the content of the string channel identified by name

pub fn set_string_channel(&self, name: &str, content: &str)

Sets the string channel identified by name with content

pub fn get_channel_data_size(&self, name: &str) -> usize

returns the size of data stored in the channel identified by name

pub fn get_pvs_channel(
    &self,
    name: &str,
    pvs_data: &mut PvsDataExt
) -> Result<(), Status>

Receives a PVSDAT fout from the pvsout opcode. This method will return Ok on success, Status::CS_ERROR if the channel name is not valid or the channel doesn't exist or Status::CS_MEMORY if the frame buffer lengths haven't the same size as the requested table

Arguments

• name The channel identifier.
• pvs_data Reference to tha struct which will be filled with the pvs data.

Example

let mut pvs = PvsDataExt::new(512);
cs.get_pvs_channel("1", &mut pvs);

pub fn set_pvs_channel(&self, name: &str, pvs_data: &PvsDataExt)

pub fn send_score_event(&self, event_type: char, pfields: &[f64]) -> Status

Send a new score event.

Arguments

• event_type is the score event type ('a', 'i', 'q', 'f', or 'e').
• pfields is a slice of f64 values with all the pfields for this event.

Example

let cs = Csound::new();
let pFields = [1.0, 1.0, 5.0];
while cs.perform_ksmps() == false {
    cs.send_score_event('i', &pFields);
}

pub fn send_score_event_absolute(
    &self,
    event_type: char,
    pfields: &[f64],
    time_offset: f64
) -> Status

Like Csound::send_score_event. This function inserts a score event, but at absolute time with respect to the start of performance, or from an offset set with time_offset

pub fn send_score_event_async(
    &self,
    event_type: char,
    pfields: &[f64]
) -> Status

Asynchronous version of Csound::send_score_event

pub fn send_score_event_absolute_async(
    &self,
    event_type: char,
    pfields: &[f64],
    time_offset: f64
) -> Status

Asynchronous version of Csound::send_score_event_absolute

pub fn send_input_message(&self, message: &str) -> Result<(), NulError>

Input a string (as if from a console), used for line events.

Example

let cs = Csound::new();
let pFields = [1.0, 1.0, 5.0];
while cs.perform_ksmps() == false {
    cs.send_input_message("i 2 0 0.75  1");
}

pub fn send_input_message_async(&self, message: &str) -> Result<(), NulError>

Asynchronous version of Csound::send_input_message

pub fn kill_instrument(
    &self,
    instr: f64,
    name: Option<&str>,
    mode: u32,
    allow_release: bool
) -> Status

Kills off one or more running instances of an instrument.

Arguments

• instr The numeric identifier of the instrument.
• name The string identifier of the instrument or name. If it is None, the instrument numeric identifier is used.
• mode is a sum of the following values: 0,1,2: kill all instances (1), oldest only (1), or newest (2) 4: only turnoff notes with exactly matching (fractional) instr number 8: only turnoff notes with indefinite duration (p3 < 0 or MIDI).
• allow_release if true, the killed instances are allowed to release.

pub fn key_press(&self, key: char)

Set the ASCII code of the most recent key pressed.

Arguments

• key The ASCII identifier for the key pressed.

pub fn table_length(&self, table: u32) -> Result<usize, &'static str>

Returns the length of a function table (not including the guard point), or an error message if the table doens't exist.

Arguments

• table The function table identifier.

pub fn table_get(&self, table: u32, index: u32) -> Result<f64, &'static str>

Returns the value of a slot in a function table. If the Table or index are not valid, an error message will be returned.

Arguments

• table The function table identifier.
• index The value at table[index] which will be read.

pub fn table_set(
    &self,
    table: u32,
    index: u32,
    value: f64
) -> Result<(), &'static str>

Sets the value of a slot in a function table.

Arguments

• table The function table identifier.
• index The slot at table[index] where value will be added.

Returns

An error message if the index or table are no valid

pub fn table_copy_out(
    &self,
    table: u32,
    output: &mut [f64]
) -> Result<(), &'static str>

Copies the content of a function table into a slice.

Arguments

• table The function table identifier.

Returns

An error message if the table doesn't exist or the passed slice doesn't have enough memory to content the table values.

pub fn table_copy_out_async(
    &self,
    table: u32,
    output: &mut [f64]
) -> Result<(), &'static str>

Asynchronous version of Csound:: table_copy_out

pub fn table_copy_in(&self, table: u32, src: &[f64]) -> Result<(), &'static str>

Copy the contents of an array into a given function table.

Arguments

• table The function table identifier.
• src Slice with the values to be copied into the function table

Returns

An error message if the table doesn't exist or doesn't have enough capacity.

pub fn table_copy_in_async(
    &self,
    table: u32,
    src: &[f64]
) -> Result<(), &'static str>

Asynchronous version of Csound:: table_copy_in

pub fn get_table(&self, table: u32) -> Option<Table>

Returns a Csound::Table. which could be used to read/write the table content directly( not using Csound:: table_copy_in or Csound::table_copy_out). this table will be valid along the csound instance. Returns None if the table doesn't exist.

Arguments

• table The function table identifier.

Example

let cs = Csound::new();
cs.compile_csd("some.csd");
cs.start().unwrap();
while cs.perform_ksmps() == false {
    let mut table_buff = vec![0f64; cs.table_length(1).unwrap() as usize];
    // Gets the function table 1
    let mut table = cs.get_table(1).unwrap();
    // Copies the table content into table_buff
    table.read( table_buff.as_mut_slice() ).unwrap();
    // Do some stuffs
    table.write(&table_buff.into_iter().map(|x| x*2.5).collect::<Vec<f64>>().as_mut_slice());
    // Do some stuffs
}

see Table::read or Table::write.

pub fn get_table_args(&self, table: u32) -> Option<Vec<f64>>

Gets the arguments used to construct or define a function table

Arguments

• table The function table identifier.

Returns

A vector containing the table's arguments.

• Note:* the argument list starts with the GEN number and is followed by its parameters. eg. f 1 0 1024 10 1 0.5 yields the list {10.0,1.0,0.5}.

pub fn get_table_args_slice(&self, table: u32) -> Option<&[f64]>

Gets the arguments used to construct or define a function table Similar to Csound::get_table_args but no memory will be allocated, instead a slice is returned.

pub fn is_named_gen(&self, gen: u32) -> usize

Checks if a given gen number is a named GEN

Arguments

• gen The GEN number identifier.

Returns

The GEN names's length

pub fn get_gen_name(&self, gen: u32) -> Option<String>

Returns the GEN name if it exist ans is named, else, returns None

Arguments

• gen The GEN number identifier.

Returns

A option with the GEN name or None if the GEN is not a named one or not exist.

pub fn get_opcode_list_entry(&self) -> Option<Vec<OpcodeListEntry>>

Gets an alphabetically sorted list of all opcodes. Should be called after externals are loaded by csoundCompile(). The opcode information is contained in a Csound::OpcodeListEntry

pub fn set_language(lang_code: Language)

TODO genName and appendOpcode functions

---

Argument

• lang_code can be for example any of Language variants. This affects all Csound instances running in the address space of the current process. The special language code Language::CSLANGUAGE_DEFAULT can be used to disable translation of messages and free all memory allocated by a previous call to this function. set_language() loads all files for the selected language from the directory specified by the CSSTRNGS environment variable.

pub fn get_random_seed_from_time() -> u32

Generates a random seed from time

Returns

A 32-bit unsigned integer to be used as random seed.

pub fn get_rand31(seed: &mut u32) -> Result<u32, &'static str>

Simple linear congruential random number generator: seed = seed * 742938285 % 2147483647

Returns

The next number from the pseudo-random sequence, in the range 1 to 2147483646. if the value of seed is not in the range 1 to 2147483646 an error message will be returned.

pub fn init_timer() -> RTCLOCK

Returns an initialised timer structure.

pub fn get_real_time(timer: &RTCLOCK) -> f64

Calculates a time offset

Arguments

• timer time struct since the elapsed time will be calculated.

Returns

The elapsed real time (in seconds) since the specified timer

pub fn get_cpu_time(timer: &mut RTCLOCK) -> f64

Return the elapsed CPU time (in seconds) since the specified timer structure was initialised.

Arguments

• gen The GEN number identifier.

pub fn create_circular_buffer<'a, T: 'a + Copy>(
    &'a self,
    len: u32
) -> CircularBuffer<T>

Creates a circular buffer.

Arguments

• len The buffer length.

Returns

A CircularBuffer

Example

let csound = Csound::new();
let circular_buffer = csound.create_circular_buffer::<f64>(1024);

pub fn sleep(&self, milli_seconds: usize)

pub fn audio_device_list_callback<'c, F>(&self, f: F) where
    F: FnMut(CsAudioDevice) + 'c, 

Sets a function that is called to obtain a list of audio devices. This should be set by rtaudio modules and should not be set by hosts.

pub fn play_open_audio_callback<'c, F>(&self, f: F) where
    F: FnMut(&RtAudioParams) -> Status + 'c, 

Sets a function to be called by Csound for opening real-time audio playback. This callback is used to inform the user about the current audio device Which Csound will use to play the audio samples.

Arguments

• user_func A function/closure which will receive a reference to a RtAudioParams struct.

pub fn rec_open_audio_callback<'c, F>(&self, f: F) where
    F: FnMut(&RtAudioParams) -> Status + 'c, 

Sets a function to be called by Csound for opening real-time audio recording. This callback is used to inform the user about the current audio device Which Csound will use for opening realtime audio recording. You have to return Status::CS_SUCCESS

pub fn rt_audio_play_callback<'c, F>(&self, f: F) where
    F: FnMut(&[f64]) + 'c, 

Sets a function to be called by Csound for performing real-time audio playback. A reference to a buffer with audio samples is passed to the user function in the callback. These samples have to be processed and sent to a proper audio device.

pub fn rt_audio_rec_callback<'c, F>(&self, f: F) where
    F: FnMut(&mut [f64]) -> usize + 'c, 

Sets a function to be called by Csound for performing real-time audio recording. With this callback the user can fill a buffer with samples from a custom audio module, and pass it into csound.

pub fn rt_close_callback<'c, F>(&self, f: F) where
    F: FnMut() + 'c, 

Indicates to the user when csound has closed the rtaudio device.

pub fn sense_event_callback<'c, F>(&self, f: F) where
    F: FnMut() + 'c, 

Sets callback to be called once in every control period. This facility can be used to ensure a function is called synchronously before every csound control buffer processing. It is important to make sure no blocking operations are performed in the callback.

pub fn message_string_callback<'c, F>(&self, f: F) where
    F: FnMut(MessageType, &str) + 'c, 

Sets a callback which will be called by csound to print an informational message.

Arguments

• ´f´ Function which implement the FnMut trait. The callback arguments are u32 which indicates the message atributte, and a reference to the message content.

Example

let mut cs = Csound::new();
cs.message_string_callback(|att: MessageType, message: &str| print!("{}", message));

pub fn input_channel_callback<'c, F>(&self, f: F) where
    F: FnMut(&str) -> ChannelData + 'c, 

Sets the function which will be called whenever the invalue opcode is used.

Arguments

• ´f´ Function which implement the FnMut trait. The invalue opcode will trigger this callback passing the channel name which requiere the data. This function/closure have to return the data which will be passed to that specific channel if not only return ChannelData::CS_UNKNOWN_CHANNEL. Only String and control Channels are supported.

Example

let input_channel = |name: &str|->ChannelData {
     if name == "myStringChannel"{
         let myString = "my data".to_owned();
         ChannelData::CS_STRING_CHANNEL(myString)
     }
     ChannelData::CS_UNKNOWN_CHANNEL
};
let mut cs = Csound::new();
cs.input_channel_callback(input_channel);

pub fn output_channel_callback<'c, F>(&self, f: F) where
    F: FnMut(&str, ChannelData) + 'c, 

Sets the function which will be called whenever the outvalue opcode is used.

Arguments

• ´f´ Function which implement the FnMut trait. The outvalue opcode will trigger this callback passing the channel ##name and the channel's output data encoded in the ChannelData. Only String and control Channels are supported.

Example

let output_channel = |name: &str, data:ChannelData|{
     print!("channel name:{}  data: {:?}", name, data);
};
let mut cs = Csound::new();
cs.output_channel_callback(output_channel);

pub fn file_open_callback<'c, F>(&self, f: F) where
    F: FnMut(&FileInfo) + 'c, 

Sets an external callback for receiving notices whenever Csound opens a file. The callback is made after the file is successfully opened. The following information is passed to the callback:

file_info

A FileInfo struct containing the relevant file info.

pub fn midi_in_open_callback<'c, F>(&self, f: F) where
    F: FnMut(&str) + 'c, 

Sets a function to be called by Csound for opening real-time MIDI input. This callback is used to inform to the user about the current MIDI input device.

Arguments

• user_func A function/closure which will receive a reference to a str with the device name.

pub fn midi_out_open_callback<'c, F>(&self, f: F) where
    F: FnMut(&str) + 'c, 

Sets a function to be called by Csound for opening real-time MIDI output. This callback is used to inform to the user about the current MIDI output device.

Arguments

• user_func A function/closure which will receive a reference to a str with the device name.

pub fn midi_read_callback<'c, F>(&self, f: F) where
    F: FnMut(&mut [u8]) -> usize + 'c, 

Sets a function to be called by Csound for reading from real time MIDI input. A reference to a buffer with audio samples is passed to the user function in the callback. The callback have to return the number of elements written to the buffer.

pub fn midi_write_callback<'c, F>(&self, f: F) where
    F: FnMut(&[u8]) -> usize + 'c, 

Sets a function to be called by Csound for Writing to real time MIDI input. A reference to the device buffer is passed to the user function in the callback. The passed buffer have the max length that the user is able to use, and the callback have to return the number of element written into the buffer.

pub fn midi_in_close_callback<'c, F>(&self, f: F) where
    F: FnMut() + 'c, 

Indicates to the user when csound has closed the midi input device.

pub fn midi_out_close_callback<'c, F>(&self, f: F) where
    F: FnMut() + 'c, 

Indicates to the user when csound has closed the midi output device.

pub fn yield_callback<'c, F>(&self, f: F) where
    F: FnMut() -> bool + 'c, 

Called by external software to set a function for checking system events, yielding cpu time for coopertative multitasking, etc This function is optional. It is often used as a way to 'turn off' Csound, allowing it to exit gracefully. In addition, some operations like utility analysis routines are not reentrant and you should use this function to do any kind of updating during the operation.

Returns

If this callback returns false it wont be called anymore

Trait Implementations

impl<'a> GetChannel<'a, AudioChannel> for Csound

fn get_input_channel(
    &'a self,
    name: &str,
    _: AudioChannel
) -> Result<ChannelPtr<'a, AudioChannel, Writable>, Status>

Return a ChannelPtr which represent a csound's input channel ptr. creating the channel first if it does not exist yet.

Arguments

• name The channel name.
• channel_type must be any of the following values:

• ControlChannel::ctype control data (one MYFLT value)
• AudioChannel::ctype audio data (get_ksmps() f64 values)
• StrChannel::ctype string data (u8 values with enough space to store get_channel_data_size() characters, including the NULL character at the end of the string) If the channel already exists, it must match the data type (control, audio, or string)

Note

Audio and String channels can only be created after calling compile(), because the storage size is not known until then.

Returns

A Writable ChannelPtr on success or a Status code, "Not enough memory for allocating the channel" (CS_MEMORY) "The specified name or type is invalid" (CS_ERROR) or, if a channel with the same name but incompatible type already exists, the type of the existing channel.

• Note: to find out the type of a channel without actually creating or changing it, set 'channel_type' argument to CSOUND_UNKNOWN_CHANNEL, so that the error value will be either the type of the channel, or CSOUND_ERROR if it does not exist. Operations on the channel pointer are not thread-safe by default. The host is required to take care of threadsafety by
  1. with control channels use __sync_fetch_and_add() or __sync_fetch_and_or() gcc atomic builtins to get or set a channel, if available.
  2. For string and audio channels (and controls if option 1 is not available), retrieve the channel lock with ChannelLock() and use SpinLock() and SpinUnLock() to protect access to the channel. See Top/threadsafe.c in the Csound library sources for examples. Optionally, use the channel get/set functions which are threadsafe by default.

Example

 // Creates a Csound instance
let csound = Csound::new();
csound.compile_csd(csd_filename).unwrap();
csound.start();
// Request a csound's input control channel
let control_channel = csound.get_input_channel("myChannel", ControlChannel::ctype ).unwrap();
// Writes some data to the channel
control_channel.write(10.25);
// Request a csound's input audio channel
let audio_channel = csound.get_input_channel("myAudioChannel", AudioChannel::ctype).unwrap();
// Request a csound's input string channel
let string_channel = csound.get_input_channel("myStringChannel", StrChannel::ctype).unwrap();

fn get_output_channel(
    &'a self,
    name: &str,
    _: AudioChannel
) -> Result<ChannelPtr<'a, AudioChannel, Readable>, Status>

Return a ChannelPtr which represent a csound's output channel ptr. creating the channel first if it does not exist yet.

Arguments

• name The channel name.
• channel_type must be any of the following values:

• ControlChannel::ctype control data (one MYFLT value)
• AudioChannel::ctype audio data (get_ksmps() f64 values)
• StrChannel::ctype string data (u8 values with enough space to store get_channel_data_size() characters, including the NULL character at the end of the string) If the channel already exists, it must match the data type (control, audio, or string)

Note

Audio and String channels can only be created after calling compile(), because the storage size is not known until then.

Returns

A Readable ChannelPtr on success or a Status code, "Not enough memory for allocating the channel" (CS_MEMORY) "The specified name or type is invalid" (CS_ERROR) or, if a channel with the same name but incompatible type already exists, the type of the existing channel.

• Note: to find out the type of a channel without actually creating or changing it, set 'channel_type' argument to CSOUND_UNKNOWN_CHANNEL, so that the error value will be either the type of the channel, or CSOUND_ERROR if it does not exist. Operations on the channel pointer are not thread-safe by default. The host is required to take care of threadsafety by
  1. with control channels use __sync_fetch_and_add() or __sync_fetch_and_or() gcc atomic builtins to get or set a channel, if available.
  2. For string and audio channels (and controls if option 1 is not available), retrieve the channel lock with ChannelLock() and use SpinLock() and SpinUnLock() to protect access to the channel. See Top/threadsafe.c in the Csound library sources for examples. Optionally, use the channel get/set functions which are threadsafe by default.

Example

 // Creates a Csound instance
let csound = Csound::new();
csound.compile_csd(csd_filename).unwrap();
csound.start();
// Request a csound's output control channel
let control_channel = csound.get_output_channel("myChannel", ControlChannel::ctype ).unwrap();
// Writes some data to the channel
println!("channel value {}", constrol_channel.read());
// Request a csound's output audio channel
let audio_channel = csound.get_output_channel("myAudioChannel", AudioChannel::ctype).unwrap();
println!("audio channel samples {:?}", audio_channel.read() );
// Request a csound's output string channel
let string_channel = csound.get_output_channel("myStringChannel", StrChannel::ctype).unwrap();

impl<'a> GetChannel<'a, ControlChannel> for Csound

fn get_input_channel(
    &'a self,
    name: &str,
    _: ControlChannel
) -> Result<ChannelPtr<'a, ControlChannel, Writable>, Status>

Return a ChannelPtr which represent a csound's input channel ptr. creating the channel first if it does not exist yet.

Arguments

• name The channel name.
• channel_type must be any of the following values:

• ControlChannel::ctype control data (one MYFLT value)
• AudioChannel::ctype audio data (get_ksmps() f64 values)
• StrChannel::ctype string data (u8 values with enough space to store get_channel_data_size() characters, including the NULL character at the end of the string) If the channel already exists, it must match the data type (control, audio, or string)

Note

Audio and String channels can only be created after calling compile(), because the storage size is not known until then.

Returns

A Writable ChannelPtr on success or a Status code, "Not enough memory for allocating the channel" (CS_MEMORY) "The specified name or type is invalid" (CS_ERROR) or, if a channel with the same name but incompatible type already exists, the type of the existing channel.

• Note: to find out the type of a channel without actually creating or changing it, set 'channel_type' argument to CSOUND_UNKNOWN_CHANNEL, so that the error value will be either the type of the channel, or CSOUND_ERROR if it does not exist. Operations on the channel pointer are not thread-safe by default. The host is required to take care of threadsafety by
  1. with control channels use __sync_fetch_and_add() or __sync_fetch_and_or() gcc atomic builtins to get or set a channel, if available.
  2. For string and audio channels (and controls if option 1 is not available), retrieve the channel lock with ChannelLock() and use SpinLock() and SpinUnLock() to protect access to the channel. See Top/threadsafe.c in the Csound library sources for examples. Optionally, use the channel get/set functions which are threadsafe by default.

Example

 // Creates a Csound instance
let csound = Csound::new();
csound.compile_csd(csd_filename).unwrap();
csound.start();
// Request a csound's input control channel
let control_channel = csound.get_input_channel("myChannel", ControlChannel::ctype ).unwrap();
// Writes some data to the channel
control_channel.write(10.25);
// Request a csound's input audio channel
let audio_channel = csound.get_input_channel("myAudioChannel", AudioChannel::ctype).unwrap();
// Request a csound's input string channel
let string_channel = csound.get_input_channel("myStringChannel", StrChannel::ctype).unwrap();

fn get_output_channel(
    &'a self,
    name: &str,
    _: ControlChannel
) -> Result<ChannelPtr<'a, ControlChannel, Readable>, Status>

Return a ChannelPtr which represent a csound's output channel ptr. creating the channel first if it does not exist yet.

Arguments

• name The channel name.
• channel_type must be any of the following values:

• ControlChannel::ctype control data (one MYFLT value)
• AudioChannel::ctype audio data (get_ksmps() f64 values)
• StrChannel::ctype string data (u8 values with enough space to store get_channel_data_size() characters, including the NULL character at the end of the string) If the channel already exists, it must match the data type (control, audio, or string)

Note

Audio and String channels can only be created after calling compile(), because the storage size is not known until then.

Returns

A Readable ChannelPtr on success or a Status code, "Not enough memory for allocating the channel" (CS_MEMORY) "The specified name or type is invalid" (CS_ERROR) or, if a channel with the same name but incompatible type already exists, the type of the existing channel.

• Note: to find out the type of a channel without actually creating or changing it, set 'channel_type' argument to CSOUND_UNKNOWN_CHANNEL, so that the error value will be either the type of the channel, or CSOUND_ERROR if it does not exist. Operations on the channel pointer are not thread-safe by default. The host is required to take care of threadsafety by
  1. with control channels use __sync_fetch_and_add() or __sync_fetch_and_or() gcc atomic builtins to get or set a channel, if available.
  2. For string and audio channels (and controls if option 1 is not available), retrieve the channel lock with ChannelLock() and use SpinLock() and SpinUnLock() to protect access to the channel. See Top/threadsafe.c in the Csound library sources for examples. Optionally, use the channel get/set functions which are threadsafe by default.

Example

 // Creates a Csound instance
let csound = Csound::new();
csound.compile_csd(csd_filename).unwrap();
csound.start();
// Request a csound's output control channel
let control_channel = csound.get_output_channel("myChannel", ControlChannel::ctype ).unwrap();
// Writes some data to the channel
println!("channel value {}", constrol_channel.read());
// Request a csound's output audio channel
let audio_channel = csound.get_output_channel("myAudioChannel", AudioChannel::ctype).unwrap();
println!("audio channel samples {:?}", audio_channel.read() );
// Request a csound's output string channel
let string_channel = csound.get_output_channel("myStringChannel", StrChannel::ctype).unwrap();

impl<'a> GetChannel<'a, StrChannel> for Csound

fn get_input_channel(
    &'a self,
    name: &str,
    _: StrChannel
) -> Result<ChannelPtr<'a, StrChannel, Writable>, Status>

Return a ChannelPtr which represent a csound's input channel ptr. creating the channel first if it does not exist yet.

Arguments

• name The channel name.
• channel_type must be any of the following values:

• ControlChannel::ctype control data (one MYFLT value)
• AudioChannel::ctype audio data (get_ksmps() f64 values)
• StrChannel::ctype string data (u8 values with enough space to store get_channel_data_size() characters, including the NULL character at the end of the string) If the channel already exists, it must match the data type (control, audio, or string)

Note

Audio and String channels can only be created after calling compile(), because the storage size is not known until then.

Returns

A Writable ChannelPtr on success or a Status code, "Not enough memory for allocating the channel" (CS_MEMORY) "The specified name or type is invalid" (CS_ERROR) or, if a channel with the same name but incompatible type already exists, the type of the existing channel.

• Note: to find out the type of a channel without actually creating or changing it, set 'channel_type' argument to CSOUND_UNKNOWN_CHANNEL, so that the error value will be either the type of the channel, or CSOUND_ERROR if it does not exist. Operations on the channel pointer are not thread-safe by default. The host is required to take care of threadsafety by
  1. with control channels use __sync_fetch_and_add() or __sync_fetch_and_or() gcc atomic builtins to get or set a channel, if available.
  2. For string and audio channels (and controls if option 1 is not available), retrieve the channel lock with ChannelLock() and use SpinLock() and SpinUnLock() to protect access to the channel. See Top/threadsafe.c in the Csound library sources for examples. Optionally, use the channel get/set functions which are threadsafe by default.

Example

 // Creates a Csound instance
let csound = Csound::new();
csound.compile_csd(csd_filename).unwrap();
csound.start();
// Request a csound's input control channel
let control_channel = csound.get_input_channel("myChannel", ControlChannel::ctype ).unwrap();
// Writes some data to the channel
control_channel.write(10.25);
// Request a csound's input audio channel
let audio_channel = csound.get_input_channel("myAudioChannel", AudioChannel::ctype).unwrap();
// Request a csound's input string channel
let string_channel = csound.get_input_channel("myStringChannel", StrChannel::ctype).unwrap();

fn get_output_channel(
    &'a self,
    name: &str,
    _: StrChannel
) -> Result<ChannelPtr<'a, StrChannel, Readable>, Status>

Return a ChannelPtr which represent a csound's output channel ptr. creating the channel first if it does not exist yet.

Arguments

• name The channel name.
• channel_type must be any of the following values:

• ControlChannel::ctype control data (one MYFLT value)
• AudioChannel::ctype audio data (get_ksmps() f64 values)
• StrChannel::ctype string data (u8 values with enough space to store get_channel_data_size() characters, including the NULL character at the end of the string) If the channel already exists, it must match the data type (control, audio, or string)

Note

Audio and String channels can only be created after calling compile(), because the storage size is not known until then.

Returns

A Readable ChannelPtr on success or a Status code, "Not enough memory for allocating the channel" (CS_MEMORY) "The specified name or type is invalid" (CS_ERROR) or, if a channel with the same name but incompatible type already exists, the type of the existing channel.

• Note: to find out the type of a channel without actually creating or changing it, set 'channel_type' argument to CSOUND_UNKNOWN_CHANNEL, so that the error value will be either the type of the channel, or CSOUND_ERROR if it does not exist. Operations on the channel pointer are not thread-safe by default. The host is required to take care of threadsafety by
  1. with control channels use __sync_fetch_and_add() or __sync_fetch_and_or() gcc atomic builtins to get or set a channel, if available.
  2. For string and audio channels (and controls if option 1 is not available), retrieve the channel lock with ChannelLock() and use SpinLock() and SpinUnLock() to protect access to the channel. See Top/threadsafe.c in the Csound library sources for examples. Optionally, use the channel get/set functions which are threadsafe by default.

Example

 // Creates a Csound instance
let csound = Csound::new();
csound.compile_csd(csd_filename).unwrap();
csound.start();
// Request a csound's output control channel
let control_channel = csound.get_output_channel("myChannel", ControlChannel::ctype ).unwrap();
// Writes some data to the channel
println!("channel value {}", constrol_channel.read());
// Request a csound's output audio channel
let audio_channel = csound.get_output_channel("myAudioChannel", AudioChannel::ctype).unwrap();
println!("audio channel samples {:?}", audio_channel.read() );
// Request a csound's output string channel
let string_channel = csound.get_output_channel("myStringChannel", StrChannel::ctype).unwrap();

impl Drop for Csound

fn drop(&mut self)

Executes the destructor for this type.

impl Default for Csound

fn default() -> Self

Returns the "default value" for a type.

impl Debug for Csound

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.