bse(3)

NAME

BSE-Functions - BSE Function Reference

Document Revised: Wed May 25 23:38:22 2005

SYNOPSIS

BseEngineAccessFunc(module, data);
BseEnginePollFunc(data, n_values, timeout_p, n_fds, fds, revents_filled);
BseEngineProbeFunc(data, tick_stamp, n_values, oblocks);
BseGlueBoxedToRec(boxed);
BseGlueBoxedToSeq(boxed);
BseStorageRestoreLink(data, storage, from_item, to_item, error);
bse_approx2_exp2(ex);
bse_approx2_tanh(x);
bse_approx3_exp2(ex);
bse_approx3_tanh(x);
bse_approx4_exp2(ex);
bse_approx4_tanh(x);
bse_approx5_exp2(ex);
bse_approx5_tanh(x);
bse_approx6_exp2(ex);
bse_approx6_tanh(x);
bse_approx7_exp2(ex);
bse_approx7_tanh(x);
bse_approx8_exp2(ex);
bse_approx8_tanh(x);
bse_approx9_exp2(ex);
bse_approx9_tanh(x);
bse_approx_atan1(x);
bse_approx_atan1_prescale(boost_amount);
bse_approx_qcircle1(x);
bse_approx_qcircle2(x);
bse_approx_qcircle3(x);
bse_approx_qcircle4(x);
bse_engine_add_user_callback(data, free_func);
bse_engine_configure(latency_ms, sample_freq, control_freq);
bse_engine_constrain(latency_ms, sample_freq, control_freq, block_size_p, control_raster_p);
bse_engine_dispatch();
bse_engine_garbage_collect();
bse_engine_init(run_threaded);
bse_engine_tick_stamp_from_systime(systime);
bse_engine_wait_on_trans();
bse_glue_boxed_to_value(boxed_type, boxed);
bse_idle_notify(function, data);
bse_idle_now(function, data);
bse_idle_remove(id);
bse_idle_timed(usec_delay, function, data);
bse_item_cross_link(owner, link, uncross_func);
bse_item_cross_unlink(owner, link, uncross_func);
bse_item_gather_items(item, iseq, base_type, ccheck, pcheck, data);
bse_item_gather_items_typed(item, iseq, proxy_type, container_type, allow_ancestor);
bse_item_set_internal(item, internal);
bse_item_uncross_links(owner, link);
bse_job_access(module, access_func, data, free_func);
bse_job_add_poll(poll_func, data, free_func, n_fds, fds);
bse_job_add_timer(timer_func, data, free_func);
bse_job_boundary_access(module, tick_stamp, access_func, data, free_func);
bse_job_boundary_discard(module);
bse_job_connect(src_module, src_ostream, dest_module, dest_istream);
bse_job_debug(debug);
bse_job_discard(module);
bse_job_disconnect(dest_module, dest_istream);
bse_job_flow_access(module, tick_stamp, access_func, data, free_func);
bse_job_force_reset(module);
bse_job_integrate(module);
bse_job_jconnect(src_module, src_ostream, dest_module, dest_jstream);
bse_job_jdisconnect(dest_module, dest_jstream, src_module, src_ostream);
bse_job_kill_inputs(module);
bse_job_kill_outputs(module);
bse_job_nop();
bse_job_remove_poll(poll_func, data);
bse_job_request_probe(module, n_delay_samples, n_probe_values, ochannel_bytemask, probe_func, data);
bse_job_resume_at(module, tick_stamp);
bse_job_suspend_now(module);
bse_midi_free_event(event);
bse_midi_signal_default(type);
bse_module_has_source(module, istream);
bse_module_is_scheduled(module);
bse_module_new(klass, user_data);
bse_module_new_virtual(n_iostreams, user_data, free_data);
bse_module_tick_stamp(module);
bse_msg_handler(lmsg);
bse_object_strdup_debug_handle(object);
bse_procedure_collect_input_args(proc, first_value, var_args, ivalues);
bse_procedure_marshal_valist(proc_type, first_value, marshal, marshal_data, skip_ovalues, var_args);
bse_saturate_branching(value, limit);
bse_saturate_hard(value, limit);
bse_server_get();
bse_snet_intern_child(self, child);
bse_storage_parse_item_link(self, from_item, restore_link, data);
bse_trans_add(trans, job);
bse_trans_commit(trans);
bse_trans_commit_delayed(trans, tick_stamp);
bse_trans_dismiss(trans);
bse_trans_merge(trans1, trans2);
bse_trans_open();
bse_transact(job, ...);
gsl_data_clip_sample(dhandle, cconfig, result);
gsl_data_find_block(handle, n_values, values, epsilon);
gsl_data_handle_new_crop(src_handle, n_head_cut, n_tail_cut);
gsl_data_handle_new_cut(src_handle, cut_offset, n_cut_values);
gsl_data_make_fade_ramp(dhandle, min_pos, max_pos, length_p);
gsl_filter_butter_bp(iorder, freq1, freq2, epsilon, a, b);
gsl_filter_butter_bs(iorder, freq1, freq2, epsilon, a, b);
gsl_filter_butter_hp(iorder, freq, epsilon, a, b);
gsl_filter_butter_lp(iorder, freq, epsilon, a, b);
gsl_filter_fir_approx(iorder, freq, value);
gsl_filter_sine_scan(order, a, b, freq, n_values);
gsl_filter_tscheb1_bp(iorder, freq1, freq2, epsilon, a, b);
gsl_filter_tscheb1_bs(iorder, freq1, freq2, epsilon, a, b);
gsl_filter_tscheb1_hp(iorder, freq, epsilon, a, b);
gsl_filter_tscheb1_lp(iorder, freq, epsilon, a, b);
gsl_filter_tscheb2_bp(iorder, freq1, freq2, steepness, epsilon, a, b);
gsl_filter_tscheb2_bs(iorder, freq1, freq2, steepness, epsilon, a, b);
gsl_filter_tscheb2_hp(iorder, freq, steepness, epsilon, a, b);
gsl_filter_tscheb2_lp(iorder, freq, steepness, epsilon, a, b);
gsl_filter_tscheb2_steepness(iorder, c_freq, epsilon, residue);
gsl_filter_tscheb2_steepness_db(iorder, c_freq, epsilon, stopband_db);
gsl_hfile_close(hfile);
gsl_hfile_open(file_name);
gsl_hfile_pread(hfile, offset, n_bytes, bytes);
gsl_hfile_zoffset(hfile);
gsl_power2_fftac(n_values, ri_values_in, ri_values_out);
gsl_power2_fftar(n_values, r_values_in, ri_values_out);
gsl_power2_fftsc(n_values, ri_values_in, ri_values_out);
gsl_power2_fftsr(n_values, ri_values_in, r_values_out);
gsl_rfile_close(rfile);
gsl_rfile_length(rfile);
gsl_rfile_name(rfile);
gsl_rfile_open(file_name);
gsl_rfile_position(rfile);
gsl_rfile_pread(rfile, offset, n_bytes, bytes);
gsl_rfile_read(rfile, n_bytes, bytes);
gsl_rfile_seek_set(rfile, offset);
gsl_thread_awake_before(tick_stamp);
gsl_tick_stamp();
gsl_tick_stamp_last();

DESCRIPTION

BseEngineAccessFunc(module, data);

	module;	Module to operate on
	data;	Accessor data

The BseEngineAccessFunc is a user supplied callback function which can access a module in times it is not processing. Accessors are usually used to either read out a module's current state, or to modify its state. An accessor may only operate on the data and the module passed in to it.

BseEnginePollFunc(data, n_values, timeout_p, n_fds, fds, revents_filled);

	data;	Data of poll function
	n_values;	Minimum number of values the engine wants to process
	timeout_p;	Location of timeout value
	n_fds;	Number of file descriptors used for polling
	fds;	File descriptors to be used for polling
	revents_filled;	Indicates whether fds actually have their ->revents field filled with valid data.
RETURNS:		A boolean value indicating whether the engine should process data right now

The BseEnginePollFunc is a user supplied callback function which can be hooked into the BSE Engine. The engine uses the poll functions to determine whether processing of n_values in its module network is necessary. In order for the poll functions to react to extern events, such as device driver status changes, the engine will poll(2) the fds of the poll function and invoke the callback with revents_filled==TRUE if any of its fds changed state. The callback may also be invoked at other random times with revents_filled=FALSE. It is supposed to return TRUE if network processing is currently necessary, and FALSE if not. If FALSE is returned, timeout_p may be filled with the number of milliseconds the engine should use for polling at maximum.

BseEngineProbeFunc(data, tick_stamp, n_values, oblocks);

	data;	user data passed in to bse_job_probe_request()
	tick_stamp;	engine time in microseconds of the probe
	n_values;	number of values probed
	oblocks;	array of probe value block per output channel

A BseEngineProbeFunc() is provided by users as a means to be notified about a completed probe. This function is executed in the user thread. Per each output channel that a probe has been requested through bse_job_request_probe(), a block of probe values is supplied as oblocks[channel-index]. These blocks are allocate via g_new() and may be "stolen" by assigning NULL to the respective pointer (the caller then is responsible to g_free() the block). Note that n_values may be 0 in case the module to be probed was inactive. The blocks still contain bse_engine_block_size() values regardless.

BseGlueBoxedToRec(boxed);

	boxed;	the boxed value to be converted into a record
RETURNS:		a GC owned SfiRec*

Construct a new SfiRec from a boxed value.

BseGlueBoxedToSeq(boxed);

	boxed;	the boxed value to be converted into a sequence
RETURNS:		a GC owned SfiSeq*

Construct a new SfiSeq from a boxed value.

BseStorageRestoreLink(data, storage, from_item, to_item, error);

	data;	user data
	storage;	BseStorage instance
	from_item;	link owner
	to_item;	link target or NULL
	error;	error string describing failing link lookups

BseStorageRestoreLink() is a user supplied handler to be called at the end of a parsing stage, once object references could be resolved. Failing resolutions are indicated by non NULLerror strings.

bse_approx2_exp2(ex);

float	ex;	exponent within [-127..+127]
RETURNS:		y approximating 2^ex

Fast approximation of 2 raised to the power of ex. Within -1..+1, the error stays below 0.01275 which corresponds to a sample precision of 6.2 bit, the average error amounts to 0.001914. For integer values of ex (i.e. ex - floor (ex) -> 0), the error approaches zero. On a 2GHz machine, execution takes roughly 12.81 ns.

bse_approx2_tanh(x);

float	x;	exponent within [-127..+127]
RETURNS:		y approximating tanh(x)

Fast approximation of the hyperbolic tangent of x. Within -1..+1, the error stays below 0.00436 which corresponds to a sample precision of 7.8 bit, the average error amounts to 0.00069220. On a 2GHz machine, execution takes roughly 24.48 ns.

bse_approx3_exp2(ex);

float	ex;	exponent within [-127..+127]
RETURNS:		y approximating 2^ex

Fast approximation of 2 raised to the power of ex. Within -1..+1, the error stays below 0.001123415 which corresponds to a sample precision of 9.7 bit, the average error amounts to 0.000133. For integer values of ex (i.e. ex - floor (ex) -> 0), the error approaches zero. On a 2GHz machine, execution takes roughly 13.74 ns.

bse_approx3_tanh(x);

float	x;	exponent within [-127..+127]
RETURNS:		y approximating tanh(x)

Fast approximation of the hyperbolic tangent of x. Within -1..+1, the error stays below 0.0003857 which corresponds to a sample precision of 7.8 bit, the average error amounts to 0.00004827. On a 2GHz machine, execution takes roughly 25.78 ns.

bse_approx4_exp2(ex);

float	ex;	exponent within [-127..+127]
RETURNS:		y approximating 2^ex

Fast approximation of 2 raised to the power of ex. Within -1..+1, the error stays below 7.876055e-05 which corresponds to a sample precision of 13.6 bit, the average error amounts to 7.7012792e-06. For integer values of ex (i.e. ex - floor (ex) -> 0), the error approaches zero. On a 2GHz machine, execution takes roughly 16.46 ns.

bse_approx4_tanh(x);

float	x;	exponent within [-127..+127]
RETURNS:		y approximating tanh(x)

Fast approximation of the hyperbolic tangent of x. Within -1..+1, the error stays below 2.7017507e-05 which corresponds to a sample precision of 15.1 bit, the average error amounts to 2.799594e-06. On a 2GHz machine, execution takes roughly 28.41 ns.

bse_approx5_exp2(ex);

float	ex;	exponent within [-127..+127]
RETURNS:		y approximating 2^ex

Fast approximation of 2 raised to the power of ex. Within -1..+1, the error stays below 4.60807023e-06 which corresponds to a sample precision of 17.7 bit, the average error amounts to 3.842199e-07. For integer values of ex (i.e. ex - floor (ex) -> 0), the error approaches zero. On a 2GHz machine, execution takes roughly 18.51 ns.

bse_approx5_tanh(x);

float	x;	exponent within [-127..+127]
RETURNS:		y approximating tanh(x)

Fast approximation of the hyperbolic tangent of x. Within -1..+1, the error stays below 1.582042006e-06 which corresponds to a sample precision of 19.2 bit, the average error amounts to 1.42780810e-07. On a 2GHz machine, execution takes roughly 30.35 ns.

bse_approx6_exp2(ex);

float	ex;	exponent within [-127..+127]
RETURNS:		y approximating 2^ex

Fast approximation of 2 raised to the power of ex. Within -1..+1, the error stays below 2.5505813e-07 which corresponds to a sample precision of 21.9 bit, the average error amounts to 2.1028377e-08. For integer values of ex (i.e. ex - floor (ex) -> 0), the error approaches zero. On a 2GHz machine, execution takes roughly 21.84 ns.

bse_approx6_tanh(x);

float	x;	exponent within [-127..+127]
RETURNS:		y approximating tanh(x)

Fast approximation of the hyperbolic tangent of x. Within -1..+1, the error stays below 9.7878796e-08 which corresponds to a sample precision of 23.2 bit, the average error amounts to 1.3016999e-08. On a 2GHz machine, execution takes roughly 34.29 ns.

bse_approx7_exp2(ex);

float	ex;	exponent within [-127..+127]
RETURNS:		y approximating 2^ex

Fast approximation of 2 raised to the power of ex. Within -1..+1, the error stays below 4.1074325e-08 which corresponds to a sample precision of 24.5 bit, the average error amounts to 7.7448985e-09. For integer values of ex (i.e. ex - floor (ex) -> 0), the error approaches zero. On a 2GHz machine, execution takes roughly 23.79 ns.

bse_approx7_tanh(x);

float	x;	exponent within [-127..+127]
RETURNS:		y approximating tanh(x)

Fast approximation of the hyperbolic tangent of x. Within -1..+1, the error stays below 4.4375671e-08 which corresponds to a sample precision of 24.4 bit, the average error amounts to 9.5028421e-09. On a 2GHz machine, execution takes roughly 36.86 ns.

bse_approx8_exp2(ex);

float	ex;	exponent within [-127..+127]
RETURNS:		y approximating 2^ex

Fast approximation of 2 raised to the power of ex. Within -1..+1, the error stays below 4.1074325e-08 which corresponds to a sample precision of 24.5 bit, the average error amounts to 7.6776048e-09. Note that there is no significant precision increment over bse_approx7_exp2(). For integer values of ex (i.e. ex - floor (ex) -> 0), the error approaches zero. On a 2GHz machine, execution takes roughly 26.59 ns.

bse_approx8_tanh(x);

float	x;	exponent within [-127..+127]
RETURNS:		y approximating tanh(x)

Fast approximation of the hyperbolic tangent of x. Within -1..+1, the error stays below 4.4375671e-08 which corresponds to a sample precision of 24.4 bit, the average error amounts to 9.49155722e-09. Note that there is no significant precision increment over bse_approx7_tanh(). On a 2GHz machine, execution takes roughly 42.03 ns.

bse_approx9_exp2(ex);

float	ex;	exponent within [-127..+127]
RETURNS:		y approximating 2^ex

Fast approximation of 2 raised to the power of ex. Within -1..+1, the error stays below 4.1074325e-08 which corresponds to a sample precision of 24.5 bit, the average error amounts to 7.677515903e-09. Note that there is no significant precision increment over bse_approx7_exp2(). For integer values of ex (i.e. ex - floor (ex) -> 0), the error approaches zero. On a 2GHz machine, execution takes roughly 29.40 ns.

bse_approx9_tanh(x);

float	x;	exponent within [-127..+127]
RETURNS:		y approximating tanh(x)

Fast approximation of the hyperbolic tangent of x. Within -1..+1, the error stays below 4.4375671e-08 which corresponds to a sample precision of 24.4 bit, the average error amounts to 9.49141881e-09. Note that there is no significant precision increment over bse_approx7_tanh(). On a 2GHz machine, execution takes roughly 43.83 ns.

bse_approx_atan1(x);

register double

x;

x as in atan(x)

Fast atan(x)/(PI/2) approximation, with maximum error < 0.01 and bse_approx_atan1(0)==0, according to the formula: n1 = -0.41156875521951602506487246309908; n2 = -1.0091272542790025586079663559158; d1 = 0.81901156857081841441890603235599; d2 = 1.0091272542790025586079663559158; positive_atan1(x) = 1 + (n1 * x + n2) / ((1 + d1 * x) * x + d2);

bse_approx_atan1_prescale(boost_amount);

	boost_amount;	boost amount between [0..1]
RETURNS:		prescale factor for bse_approx_atan1()

Calculate the prescale factor for bse_approx_atan1(x*prescale) from a linear boost factor, where 0.5 amounts to prescale=1.0, 1.0 results in maximum boost and 0.0 results in maximum attenuation.

bse_approx_qcircle1(x);

register double	x;	x within [0..1]
RETURNS:		y for circle approximation within [0..1]

Fast approximation of the upper right quadrant of a circle. Errors at x=0 and x=1 are zero, for the rest of the curve, the error wasn't minimized, but distributed to best fit the curverture of a quarter circle. The maximum error is below 0.092.

bse_approx_qcircle2(x);

register double	x;	x within [0..1]
RETURNS:		y for circle approximation within [0..1]

Fast approximation of the upper left quadrant of a circle. Errors at x=0 and x=1 are zero, for the rest of the curve, the error wasn't minimized, but distributed to best fit the curverture of a quarter circle. The maximum error is below 0.092.

bse_approx_qcircle3(x);

register double	x;	x within [0..1]
RETURNS:		y for circle approximation within [0..1]

Fast approximation of the lower left quadrant of a circle. Errors at x=0 and x=1 are zero, for the rest of the curve, the error wasn't minimized, but distributed to best fit the curverture of a quarter circle. The maximum error is below 0.092.

bse_approx_qcircle4(x);

register double	x;	x within [0..1]
RETURNS:		y for circle approximation within [0..1]

Fast approximation of the lower right quadrant of a circle. Errors at x=0 and x=1 are zero, for the rest of the curve, the error wasn't minimized, but distributed to best fit the curverture of a quarter circle. The maximum error is below 0.092.

bse_engine_add_user_callback(data, free_func);

gpointer	data;	Data passed in to the free_func
BseFreeFunc	free_func;	Function to free data (executed in user thread)

Queues data to be collected by bse_engine_garbage_collect(), so free_func() will be called with data as argument during the next garbage collection cycle in the user thread. This function is MT-safe and may be called from any thread.

bse_engine_configure(latency_ms, sample_freq, control_freq);

guint	latency_ms;	calculation latency in milli seconds
guint	sample_freq;	mixing frequency
guint	control_freq;	frequency at which to check control values or 0
RETURNS:		whether reconfiguration was successful

Reconfigure engine parameters. This function may only be called after engine initialization and can only succeed if no modules are currently integrated.

bse_engine_constrain(latency_ms, sample_freq, control_freq, block_size_p, control_raster_p);

guint	latency_ms;	calculation latency in milli seconds
guint	sample_freq;	mixing frequency
guint	control_freq;	frequency at which to check control values or 0
guint*	block_size_p;	location of number of values to process block wise
guint*	control_raster_p;	location of number of values to skip between control values

Calculate a suitable block size and control raster for a sample_freq at a specific latency_ms (the latency should be > 0). The control_freq if specified should me much smaller than the sample_freq. It determines how often control values are to be checked when calculating blocks of sample values. The block size determines the amount by which the global tick stamp (see gsl_tick_stamp()) is updated everytime the whole module network completed processing block size values. This function is MT-safe and may be called prior to engine initialization.

bse_engine_dispatch();

Perform necessary work the engine has to handle in the user thread. This function may only be called from the user thread, since it will invoke BseFreeFunc() functions (see bse_engine_garbage_collect()) and do other things which are guranteed to be executed in the user thread.

bse_engine_garbage_collect();

BSE Engine user thread function. Collects processed jobs and transactions from the engine and frees them. This involves callback invocation of BseFreeFunc() functions, e.g. from bse_job_access() or bse_job_flow_access() jobs. This function may only be called from the user thread, as BseFreeFunc() functions are guranteed to be executed in the user thread.

bse_engine_init(run_threaded);

gboolean

run_threaded;

whether the engine should be run threaded

Initialize the BSE Engine, this function must be called prior to any other engine related function and can only be invoked once.

bse_engine_tick_stamp_from_systime(systime);

guint64	systime;	System time in micro seconds.
RETURNS:		Engine tick stamp value

Depending on the engine's sample frequency and the time of the last global tick stamp update, calculate the corresponding engine tick stamp from a given system time. This function is MT-safe and may be called from any thread.

bse_engine_wait_on_trans();

Wait until all pending transactions have been processed by the BSE Engine. This function, when done waiting, will run a garbage collection cycle before returning. See bse_engine_garbage_collect(), the same restrictions apply to invokations of this function.

bse_glue_boxed_to_value(boxed_type, boxed);

GType	boxed_type;	type of the boxed value
gpointer	boxed;	the boxed value

Covert a boxed value into a SfiGlueValue (usually holding either a sequence or a record). The returned value is owned by the GC.

bse_idle_notify(function, data);

GSourceFunc	function;	user function
gpointer	data;	user data
RETURNS:		idle handler id, suitable for bse_idle_remove()

Queue function(data) for execution inside the main BSE thread, similar to bse_idle_now(), albeit with a lower priority. This funciton is intended to be used by code which emits asyncronous notifications. This funciton is MT-safe and may be called from any thread.

bse_idle_now(function, data);

GSourceFunc	function;	user function
gpointer	data;	user data
RETURNS:		idle handler id, suitable for bse_idle_remove()

Execute function(data) inside the main BSE thread as soon as possible. This funciton is intended to be used by code which for some reason has to be executed asyncronously. This funciton is MT-safe and may be called from any thread.

bse_idle_remove(id);

guint

id;

idle handler id

Remove or unqueue an idle handler queued by bse_idle_now() or one of its variants. This funciton is MT-safe and may be called from any thread.

bse_idle_timed(usec_delay, function, data);

guint64	usec_delay;	microsecond delay
GSourceFunc	function;	user function
gpointer	data;	user data
RETURNS:		idle handler id, suitable for bse_idle_remove()

Execute function(data) with the main BSE thread, similar to bse_idle_now(), after a delay period of usec_delay has passed. This funciton is MT-safe and may be called from any thread.

bse_item_cross_link(owner, link, uncross_func);

BseItem*	owner;	reference owner
BseItem*	link;	item to be referenced by owner
BseItemUncross	uncross_func;	notifier to be executed on uncrossing

Install a weak cross reference from owner to link. The two items must have a common ancestor when the cross link is installed. Once their ancestry changes so that they don't have a common ancestor anymore, uncross_func() is executed.

bse_item_cross_unlink(owner, link, uncross_func);

BseItem*	owner;	reference owner
BseItem*	link;	item referenced by owner
BseItemUncross	uncross_func;	notifier queued to be executed on uncrossing

Removes a cross link previously installed via bse_item_cross_link() without executing uncross_func().

bse_item_gather_items(item, iseq, base_type, ccheck, pcheck, data);

BseItem*	item;	valid BseItem from which to start gathering
BseItemSeq*	iseq;
GType	base_type;	base type of the items to gather
BseItemCheckContainer	ccheck;	container filter function
BseItemCheckProxy	pcheck;	proxy filter function
gpointer	data;	data pointer to ccheck and pcheck
RETURNS:		returns items

This function gathers items from an object hirachy, walking upwards, starting out with item. For each container passing ccheck(), all immediate children are tested for addition with pcheck.

bse_item_gather_items_typed(item, iseq, proxy_type, container_type, allow_ancestor);

BseItem*	item;	valid BseItem from which to start gathering
BseItemSeq*	iseq;
GType	proxy_type;	base type of the items to gather
GType	container_type;	base type of the containers to check for items
gboolean	allow_ancestor;	if FALSE, ancestors of item are omitted
RETURNS:		returns items

Variant of bse_item_gather_items(), the containers and items are simply filtered by checking derivation from container_type and proxy_type respectively. Gathered items may not be ancestors of item if allow_ancestor is FALSE.

bse_item_set_internal(item, internal);

gpointer	item;	valid BseItem
gboolean	internal;	TRUE or FALSE

Set whether an item should be considered internal to the BSE implementation (or implementation of another BSE object). Internal items are not stored with their parents and undo is not recorded for internal items either. Marking containers internal also affects any children they contain, in effect, the whole posterity spawned by the container is considered internal.

bse_item_uncross_links(owner, link);

BseItem*	owner;	reference owner
BseItem*	link;	item referenced by owner

Destroys all existing cross links from owner to link by executing the associated notifiers.

bse_job_access(module, access_func, data, free_func);

BseModule*	module;	The module to access
BseEngineAccessFunc	access_func;	The accessor function (executed in master thread)
gpointer	data;	Data passed in to the accessor
BseFreeFunc	free_func;	Function to free data (executed in user thread)
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which will invoke access_func on module with data when the transaction queue is processed to modify the module's state. This function is MT-safe and may be called from any thread.

bse_job_add_poll(poll_func, data, free_func, n_fds, fds);

BseEnginePollFunc	poll_func;	Poll function to add
gpointer	data;	Data of poll function
BseFreeFunc	free_func;	Function to free data
guint	n_fds;	Number of poll file descriptors
const GPollFD*	fds;	File descriptors to select(2) or poll(2) on
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which adds a poll function to the engine. The poll function is used by the engine to determine whether processing is currently necessary. This function is MT-safe and may be called from any thread.

bse_job_add_timer(timer_func, data, free_func);

BseEngineTimerFunc	timer_func;	Timer function to add
gpointer	data;	Data of timer function
BseFreeFunc	free_func;	Function to free data
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which adds a timer function to the engine. The timer function is called after the engine caused new tick stamp updates. This function is MT-safe and may be called from any thread.

bse_job_boundary_access(module, tick_stamp, access_func, data, free_func);

BseModule*	module;	The module to access
guint64	tick_stamp;	Engine time stamp
BseEngineAccessFunc	access_func;	The accessor function
gpointer	data;	Data passed in to the accessor
BseFreeFunc	free_func;	Function to free data
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which inserts access_func with data into the boundary job queue of module. Boundary jobs are executed at block boundaries, after all ordinary jobs have been processed and before global time stamp counter passed tick_stamp. Boundary jobs queued for executaion after a node's destruction will not be executed but destroyed together with the node. This function is MT-safe and may be called from any thread.

bse_job_boundary_discard(module);

BseModule*	module;	The module to access
RETURNS:		New job suitable for bse_trans_add()

Discard module at block boundaries, after all ordinary jobs have been processed. This job type should be used instead of jobs from bse_job_discard() in situations where queueing of past-discard jobs before the next block boundary is hard to avoid (such as queing disconnection/suspend jobs from within process()). This function is MT-safe and may be called from any thread.

bse_job_connect(src_module, src_ostream, dest_module, dest_istream);

BseModule*	src_module;	Module with output stream
guint	src_ostream;	Index of output stream of src_module
BseModule*	dest_module;	Module with unconnected input stream
guint	dest_istream;	Index of input stream of dest_module
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which connects the ouput stream src_ostream of module src_module to the input stream dest_istream of module dest_module (it is an error if the input stream is already connected by the time the job is executed). This function is MT-safe and may be called from any thread.

bse_job_debug(debug);

const gchar*	debug;	Debug message
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which issues debug message when the job is executed. This function is meant for debugging purposes during development phase only and shouldn't be used in production code. This function is MT-safe and may be called from any thread.

bse_job_discard(module);

BseModule*	module;	The module to discard
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which removes module from the engine and destroys it. This function is MT-safe and may be called from any thread.

bse_job_disconnect(dest_module, dest_istream);

BseModule*	dest_module;	Module with connected input stream
guint	dest_istream;	Index of input stream of dest_module
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which causes the input stream dest_istream of dest_module to be disconnected (it is an error if the input stream isn't connected by the time the job is executed). This function is MT-safe and may be called from any thread.

bse_job_flow_access(module, tick_stamp, access_func, data, free_func);

BseModule*	module;	The module to access
guint64	tick_stamp;	Engine time stamp
BseEngineAccessFunc	access_func;	The accessor function
gpointer	data;	Data passed in to the accessor
BseFreeFunc	free_func;	Function to free data
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which inserts access_func with data into the flow job queue of module. Flow jobs are jobs with limited impact on modules, which are executed during flow system progress at specific times. Once the time stamp counter of module passed tick_stamp, access_func is called to modify the module's state. Flow jobs queued for executaion after a node's destruction will not be executed but destroyed together with the node. This function is MT-safe and may be called from any thread.

bse_job_force_reset(module);

BseModule*	module;	The module to be reset
RETURNS:		New job suitable for bse_trans_add()

Forces a reset of module before its next call to process(), if its class provides a reset() implementation. This is usually not a good idea, as forcing an immediate reset can lead to multiple unnecessary reset() invocations. The logic used to invoke reset() automatically is usually good enough to cover all required cases. This function is MT-safe and may be called from any thread.

bse_job_integrate(module);

BseModule*	module;	The module to integrate
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job to integrate module into the engine. This function is MT-safe and may be called from any thread.

bse_job_jconnect(src_module, src_ostream, dest_module, dest_jstream);

BseModule*	src_module;	Module with output stream
guint	src_ostream;	Index of output stream of src_module
BseModule*	dest_module;	Module with unconnected joint input stream
guint	dest_jstream;	Index of joint input stream of dest_module
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which connects the ouput stream src_ostream of module src_module to the joint input stream dest_istream of module dest_module. This function is MT-safe and may be called from any thread.

bse_job_jdisconnect(dest_module, dest_jstream, src_module, src_ostream);

BseModule*	dest_module;	Module with connected input stream
guint	dest_jstream;	Index of input stream of dest_module
BseModule*	src_module;	Module with output stream
guint	src_ostream;	Index of output stream of src_module
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which causes the joint input stream dest_jstream of dest_module to be disconnected from the output stream src_ostream of src_module (it is an error if this connection isn't established by the time the job is executed). Beware, the order of dest_module and src_module is different from bse_job_jconnect(). This function is MT-safe and may be called from any thread.

bse_job_kill_inputs(module);

BseModule*	module;	Module with input streams
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which causes all connected input streams of module to be disconnected, like it's done upon discarding the module. This function is MT-safe and may be called from any thread.

bse_job_kill_outputs(module);

BseModule*	module;	Module with output streams
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which causes all connected output streams of module to be disconnected, like it's done upon discarding the module. This function is MT-safe and may be called from any thread.

bse_job_nop();

RETURNS:

New job suitable for bse_trans_add()

Create a new transaction job which does nothing. The job enforces a roundtrip to the engine's master thread however, which may be relevant when comitting otherwise empty transactions and calling bse_engine_wait_on_trans(). This function is MT-safe and may be called from any thread.

bse_job_remove_poll(poll_func, data);

BseEnginePollFunc	poll_func;	Poll function to remove
gpointer	data;	Data of poll function
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which removes a previously inserted poll function from the engine. This function is MT-safe and may be called from any thread.

bse_job_request_probe(module, n_delay_samples, n_probe_values, ochannel_bytemask, probe_func, data);

	module;	The module to access
	n_delay_samples;	Number of samples to wait before taking probes
	n_probe_values;	Number of probe values to take
	ochannel_bytemask;	One byte per ochannel, bytes != 0 indicate a probe request
	probe_func;	Function invoked with data in the user thread
	data;	Data passed in to the accessor
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which inserts probe_func with data into the job queue of module. Probe jobs are jobs which collect data from a given set of output channels of a module as probe data. The job then returns to the user thread before the next block boundary, and probe_func() will be invoked as early as possible. There's no free_func() supplied to delete data, because such a function would always be called immediately after probe_func(). So instead, any data specific release handling should be integrated into probe_func(). The ochannel_bytemask must point to an array of bytes with a size equal to the number of output channels of module. This function is MT-safe and may be called from any thread.

bse_job_resume_at(module, tick_stamp);

BseModule*	module;	Module to resume
guint64	tick_stamp;	Sample tick at which to resume module
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which inserts a resumption event into the job queue of module. Once the time stamp counter of module passed tick_stamp, if it is supended, its reset() method is called and the module is resumed, causing it's process() method to be called again. Resuming a module also resumes all input modules it has, unless those were explicitely suspended via bse_job_suspend_now(). This function is MT-safe and may be called from any thread.

bse_job_suspend_now(module);

BseModule*	module;	Module not currently suspended
RETURNS:		New job suitable for bse_trans_add()

Create a new transaction job which suspends the module and all it's input modules which don't have other non-suspended output connections. Suspension of a module prevents it's process() method from being called, it's outputs are simply filled with zero's instead. This function is MT-safe and may be called from any thread.

bse_midi_free_event(event);

BseMidiEvent*

event;

BseMidiEvent structure

Free the event and all data associated with it. This function is MT-safe and may be called from any thread.

bse_midi_signal_default(type);

BseMidiSignalType

type;

BseMidiSignalType type

Get the initial default value for a midi signal. This function is MT-safe and may be called from any thread.

bse_module_has_source(module, istream);

BseModule*	module;	a BSE Engine Module
guint	istream;	Index of input stream
RETURNS:		whether the module has a possible input

Check whether istream may be disconnected via bse_job_disconnect(). This is not an indication for whether BSE_MODULE_ISTREAM (module, istream).connected will be TRUE during process(), as the source may be a dangling virtual module, resulting in BSE_MODULE_ISTREAM (module, istream).connected being FALSE. See also bse_module_new_virtual(). This function is MT-safe and may be called from any thread.

bse_module_is_scheduled(module);

BseModule*	module;	a BSE Engine Module
RETURNS:		whether the module is scheduled

Check whether module is part of the schedule required to calculate the signal flow up to the consumer modules. This state may frequently change with for instance connection changes of other modules. This function is MT-safe and may be called from any thread.

bse_module_new(klass, user_data);

const BseModuleClass*	klass;	the BseModuleClass which determines the module's behaviour
gpointer	user_data;	user data pointer
RETURNS:		a newly created module

Create a new module with methods specified in klass and a user_data field set to user_data. The returned module can then be integrated into the engine with bse_job_integrate(). This function is MT-safe and may be called from any thread.

bse_module_new_virtual(n_iostreams, user_data, free_data);

guint	n_iostreams;	number of input and output streams
gpointer	user_data;	user data, stored in module->user_data
BseFreeFunc	free_data;	function to free user_data when the module is discarded
RETURNS:		a newly created module

Create a new virtual module which has n_iostreams input streams and n_iostreams output streams. Simply put, virtual modules just pass all input stream signals through to the corresponsding output stream. However, they are cheaper to compute than a literal module implementation that just passes through all data in its progress() method, because the connections can be virtualized in a connection optimization stage during scheduling, so that they don't end up in the list of modules which need to be processed during calculation phase. Beware though, flow jobs may not be scheduled on virtual modules (thusly, suspend jobs cannot be queued on them either), as virtual modules are ignored during calculation phase. They do, however, work just like ordinary modules with regards to suspension propagation, so the suspension state from output modules does only propagate across the virtual module to its input modules, if all its outputs are suspended. Instead of a single virtual module with multiple input/output streams, multiple virtual modules can be used if suspension is desired to propagate per stream. This function is MT-safe and may be called from any thread.

bse_module_tick_stamp(module);

BseModule*	module;	a BSE Engine Module
RETURNS:		the module's tick stamp, indicating its process status

Any thread may call this function on a valid engine module. The module specific tick stamp is updated to gsl_tick_stamp() + n_values every time its BseProcessFunc() function was called. See also gsl_tick_stamp(). This function is MT-safe and may be called from any thread.

bse_msg_handler(lmsg);

const SfiMessage*

lmsg;

BSE log handler, suitable for sfi_msg_set_thread_handler(). This function is MT-safe and may be called from any thread.

bse_object_strdup_debug_handle(object);

gpointer	object;	supposedly valid GObject pointer
RETURNS:		newly allocated string

Construct a debugging identifier for object. No mutable object members are accessed, so as long as the caller keeps object alive for the duration of the function call, this function is MT-safe and may be called from any thread.

bse_procedure_collect_input_args(proc, first_value, var_args, ivalues);

	proc;	valid BseProcedureClass
	first_value;	the first input argument if not to be collected
	var_args;	va_list to collect input args from
	ivalues;	uninitialized GValue array with at least proc->n_in_pspecs members
RETURNS:		BseErrorType value of error if any occoured during collection

Collect input arguments for a procedure call from a va_list. The first value may be supplied as first_value and will then not be collected. ivalues must be at least proc->n_in_pspecs elements long and all elements will be initialized after the function returns (even in error cases). first_value may be the same adress as ivalues, in whic hcase the first argument is entirely ignored and collection simply starts out with the second argument.

bse_procedure_marshal_valist(proc_type, first_value, marshal, marshal_data, skip_ovalues, var_args);

GType	proc_type;	a type derived from BSE_TYPE_PROCEDURE
const GValue*	first_value;	the first input argument if not to be collected
BseProcedureMarshal	marshal;	function marshalling the procedure call or NULL
gpointer	marshal_data;	data passed in to marshal
gboolean	skip_ovalues;	whether return value locations should be collected and filled in
va_list	var_args;	va_list to collect input args from
RETURNS:		BseErrorType value of error if any occoured

Collect input arguments for a procedure call from a va_list and call the procedure, optionally via marshal. If skip_ovalues is FALSE, the procedure return values will be stored in return value locations also collected from var_args.

bse_saturate_branching(value, limit);

double	value;	value to saturate
double	limit;	limit not to be exceeded by value
RETURNS:		value bounded by -limit and limit

Clamp value within -limit and +limit. Limiting is performed by executing conditions and branches, so it will probably run slower than bse_saturate_hard() on many machines. On a 2GHz machine, execution takes roughly 8.29 ns.

bse_saturate_hard(value, limit);

double	value;	value to saturate
double	limit;	limit not to be exceeded by value
RETURNS:		value bounded by -limit and limit

Clamp value within -limit and +limit. Limiting is performed by floating point operations only, thus executing faster than condition based branching code on most modern architectures. On a 2GHz machine, execution takes roughly 6.86 ns.

bse_server_get();

RETURNS:

Global BSE Server

Retrieve the global BSE server object.

bse_snet_intern_child(self, child);

BseSNet*	self;	valid BseSNet
gpointer	child;	valid BseItem, which is a child of self

Mark child as internal via bse_item_set_internal() and add special protection so to not destroy it automatically upon g_object_dispose().

bse_storage_parse_item_link(self, from_item, restore_link, data);

BseStorage*	self;
BseItem*	from_item;	link owner
BseStorageRestoreLink	restore_link;	BseStorageRestoreLink handler to be called once the link was resolved
gpointer	data;	user data passed into restore_link()
RETURNS:		expected token in case of a parsing error (G_TOKEN_NONE on success)

Parse an item link statement and return the expected token if a parsing error occours. Item links are resolved at the end of the parsing stage by calling the user supplied handler restore_link() with the link target amongst its arguments (see BseStorageRestoreLink()).

bse_trans_add(trans, job);

BseTrans*	trans;	Opened transaction
BseJob*	job;	Job to add

Append a job to an opened transaction. This function is MT-safe and may be called from any thread.

bse_trans_commit(trans);

BseTrans*	trans;	open transaction
RETURNS:		tick stamp of job execution

Close the transaction and commit it to the engine. The engine will execute the jobs contained in this transaction as soon as it has completed its current processing cycle, at which point gsl_tick_stamp() matches the returned tick stamp. The jobs will be executed in the exact order they were added to the transaction. This function is MT-safe and may be called from any thread.

bse_trans_commit_delayed(trans, tick_stamp);

BseTrans*	trans;	open transaction
guint64	tick_stamp;	earliest stamp

Commit the transaction like bse_trans_commit(), but make sure that the commit happens no earlier than tick_stamp. This function will block until the commit occoured, so it will not return any earlier than tick_stamp. This function is MT-safe and may be called from any thread.

bse_trans_dismiss(trans);

BseTrans*

trans;

Opened transaction

Close and discard the transaction, causes destruction of all jobs currently contained in it and prevents their execution. This function is MT-safe and may be called from any thread.

bse_trans_merge(trans1, trans2);

BseTrans*	trans1;	open transaction
BseTrans*	trans2;	open transaction
RETURNS:		open transaction

Merge two open transactions by appending the jobs of trans2 to the jobs of trans1, returning the resulting transaction. This function is MT-safe and may be called from any thread.

bse_trans_open();

RETURNS:

Newly opened empty transaction

Open up a new transaction to commit jobs to the BSE Engine. While the distinct functions to operate on a transaction are MT-safe, the caller has to take measures himself, to assure that only one function operates on the transaction at a time. This function is MT-safe and may be called from any thread.

bse_transact(job, ...);

	job;	First job
	...;	NULL terminated job list

Convenience function which openes up a new transaction, collects the NULL terminated job list passed to the function, and commits the transaction. This function is MT-safe and may be called from any thread.

gsl_data_clip_sample(dhandle, cconfig, result);

GslDataHandle*	dhandle;	valid and opened GslDataHandle
GslDataClipConfig*	cconfig;	clip configuration
GslDataClipResult*	result;	clip result
RETURNS:		error code as stored in result

Clip silence at head and/or tail of a data handle according to a given threshold and optionally produce a fade ramp.

gsl_data_find_block(handle, n_values, values, epsilon);

GslDataHandle*	handle;	an open GslDataHandle
guint	n_values;	amount of values to look for
const gfloat*	values;	values to find
gfloat	epsilon;	maximum difference upon comparisions
RETURNS:		position of values in data handle or -1

Find the position of a block of values within a data handle, where all values compare to the reference values with a delta smaller than epsilon.

gsl_data_handle_new_crop(src_handle, n_head_cut, n_tail_cut);

GslDataHandle*	src_handle;	source GslDataHandle
GslLong	n_head_cut;	number of values to cut at data handle head
GslLong	n_tail_cut;	number of values to cut at data handle tail
RETURNS:		a newly created data handle

Create a new data handle containing the contents of src_handle minus n_head_cut values at the start and n_tail_cut values at the end.

gsl_data_handle_new_cut(src_handle, cut_offset, n_cut_values);

GslDataHandle*	src_handle;	source GslDataHandle
GslLong	cut_offset;	offset of gap into src_handle
GslLong	n_cut_values;	length of gap in src_handle
RETURNS:		a newly created data handle

Create a new data handle containing the contents of src_handle minus n_cut_values at offset cut_offset.

gsl_data_make_fade_ramp(dhandle, min_pos, max_pos, length_p);

	dhandle;	valid and opened GslDataHandle
	min_pos;	position within dhandle
	max_pos;	position within dhandle
	length_p;	location to store the length of the fade ramp in
RETURNS:		newly allocated float block with fade ramp

Create a float value block of abs (max_pos - min_pos) values, which contain a fade ramp of values from dhandle, with min_pos indicating the minimum of the fade ramp and max_pos indicating its maximum.

gsl_filter_butter_bp(iorder, freq1, freq2, epsilon, a, b);

	iorder;	filter order (must be even)
	freq1;	stopband end frequency (0..pi)
	freq2;	passband end frequency (0..pi)
	epsilon;	fall off at passband frequency (0..1)
	a;	root polynomial coefficients a[0..iorder]
	b;	pole polynomial coefficients b[0..iorder]

Butterworth bandpass filter.

gsl_filter_butter_bs(iorder, freq1, freq2, epsilon, a, b);

	iorder;	filter order (must be even)
	freq1;	passband end frequency (0..pi)
	freq2;	stopband end frequency (0..pi)
	epsilon;	fall off at passband frequency (0..1)
	a;	root polynomial coefficients a[0..iorder]
	b;	pole polynomial coefficients b[0..iorder]

Butterworth bandstop filter.

gsl_filter_butter_hp(iorder, freq, epsilon, a, b);

	iorder;	filter order
	freq;	passband frequency (0..pi)
	epsilon;	fall off at passband frequency (0..1)
	a;	root polynomial coefficients a[0..iorder]
	b;	pole polynomial coefficients b[0..iorder]

Butterworth highpass filter.

gsl_filter_butter_lp(iorder, freq, epsilon, a, b);

	iorder;	filter order
	freq;	cutoff frequency (0..pi)
	epsilon;	fall off at cutoff frequency (0..1)
	a;	root polynomial coefficients a[0..iorder]
	b;	pole polynomial coefficients b[0..iorder]

Butterworth lowpass filter.

gsl_filter_fir_approx(iorder, freq, value);

	iorder;	order of the filter (must be oven, >= 2)
	freq;	the frequencies of the transfer function
	value;	the desired value of the transfer function

Approximates a given transfer function with an iorder-coefficient FIR filter. It is recommended to provide enough frequency values, so that n_points >= iorder.

gsl_filter_sine_scan(order, a, b, freq, n_values);

guint	order;	order of the iir filter
const gdouble*	a;	root polynomial coefficients of the filter a[0..order]
const gdouble*	b;	pole polynomial coefficients of the filter b[0..order]
gdouble	freq;	frequency to test
guint	n_values;	number of samples

This function sends a sine signal of the desired frequency through an IIR filter, to test the value of the transfer function at a given point. It uses gsl_iir_filter_eval to do so. Compared to a "mathematical approach" of finding the transfer function, this function makes it possible to see the effects of finite arithmetic during filter evaluation. The first half of the output signal is not considered, since a lot of IIR filters have a transient phase where also overshoot is possible. For n_values, you should specify a reasonable large value. It should be a lot larger than the filter order, and large enough to let the input signal become (close to) 1.0 multiple times.

gsl_filter_tscheb1_bp(iorder, freq1, freq2, epsilon, a, b);

	iorder;	filter order (must be even)
	freq1;	stopband end frequency (0..pi)
	freq2;	passband end frequency (0..pi)
	epsilon;	fall off at passband frequency (0..1)
	a;	root polynomial coefficients a[0..iorder]
	b;	pole polynomial coefficients b[0..iorder]

Tschebyscheff type 1 bandpass filter.

gsl_filter_tscheb1_bs(iorder, freq1, freq2, epsilon, a, b);

	iorder;	filter order (must be even)
	freq1;	passband end frequency (0..pi)
	freq2;	stopband end frequency (0..pi)
	epsilon;	fall off at passband frequency (0..1)
	a;	root polynomial coefficients a[0..iorder]
	b;	pole polynomial coefficients b[0..iorder]

Tschebyscheff type 1 bandstop filter.

gsl_filter_tscheb1_hp(iorder, freq, epsilon, a, b);

	iorder;	filter order
	freq;	passband frequency (0..pi)
	epsilon;	fall off at passband frequency (0..1)
	a;	root polynomial coefficients a[0..iorder]
	b;	pole polynomial coefficients b[0..iorder]

Tschebyscheff type 1 highpass filter.

gsl_filter_tscheb1_lp(iorder, freq, epsilon, a, b);

	iorder;	filter order
	freq;	cutoff frequency (0..pi)
	epsilon;	fall off at cutoff frequency (0..1)
	a;	root polynomial coefficients a[0..iorder]
	b;	pole polynomial coefficients b[0..iorder]

Tschebyscheff type 1 lowpass filter.

gsl_filter_tscheb2_bp(iorder, freq1, freq2, steepness, epsilon, a, b);

	iorder;	filter order (must be even)
	freq1;	stopband end frequency (0..pi)
	freq2;	passband end frequency (0..pi)
	steepness;	frequency steepness factor
	epsilon;	fall off at passband frequency (0..1)
	a;	root polynomial coefficients a[0..iorder]
	b;	pole polynomial coefficients b[0..iorder]

Tschebyscheff type 2 bandpass filter.

gsl_filter_tscheb2_bs(iorder, freq1, freq2, steepness, epsilon, a, b);

	iorder;	filter order (must be even)
	freq1;	passband end frequency (0..pi)
	freq2;	stopband end frequency (0..pi)
	steepness;	frequency steepness factor
	epsilon;	fall off at passband frequency (0..1)
	a;	root polynomial coefficients a[0..iorder]
	b;	pole polynomial coefficients b[0..iorder]

Tschebyscheff type 2 bandstop filter.

gsl_filter_tscheb2_hp(iorder, freq, steepness, epsilon, a, b);

	iorder;	filter order
	freq;	stopband frequency (0..pi)
	steepness;	frequency steepness
	epsilon;	fall off at passband frequency (0..1)
	a;	root polynomial coefficients a[0..iorder]
	b;	pole polynomial coefficients b[0..iorder]

Tschebyscheff type 2 highpass filter.

gsl_filter_tscheb2_lp(iorder, freq, steepness, epsilon, a, b);

	iorder;	filter order
	freq;	passband cutoff frequency (0..pi)
	steepness;	frequency steepness (c_freq * steepness < pi)
	epsilon;	fall off at passband frequency (0..1)
	a;	root polynomial coefficients a[0..iorder]
	b;	pole polynomial coefficients b[0..iorder]

Tschebyscheff type 2 lowpass filter. To gain a transition band between freq1 and freq2, pass arguements freq=freq1 and steepness=freq2/freq1. To specify the transition band width in fractions of octaves, pass steepness=2^octave_fraction.

gsl_filter_tscheb2_steepness(iorder, c_freq, epsilon, residue);

unsigned int	iorder;	filter order
double	c_freq;	passband cutoff frequency (0..pi)
double	epsilon;	fall off at passband frequency (0..1)
double	residue;	maximum of transfer function in stopband (0..1)

Calculates the steepness parameter for Tschebyscheff type 2 lowpass filter, based on ripple residue in the stop band.

gsl_filter_tscheb2_steepness_db(iorder, c_freq, epsilon, stopband_db);

unsigned int	iorder;	filter order
double	c_freq;	passband cutoff frequency (0..pi)
double	epsilon;	fall off at passband frequency (0..1)
double	stopband_db;	reduction in stopband in dB (>= 0)

Calculates the steepness parameter for Tschebyscheff type 2 lowpass filter, based on the ripple residue in the stop band.

gsl_hfile_close(hfile);

GslHFile*

hfile;

valid GslHFile

Close and destroy a GslHFile. This function is MT-safe and may be called from any thread.

gsl_hfile_open(file_name);

const gchar*	file_name;	name of the file to open
RETURNS:		a new opened GslHFile or NULL if an error occoured (errno set)

Open a file for reading and return the associated GSL hashed file. The motivation for using a GslHFile over normal unix file descriptors is to reduce the amount of opened unix file descriptors and to ensure thread safety upon reading offset relative byte blocks. Multiple open GslHFiles with equal file names will share a single unix file descriptor as long as the file wasn't modified meanwhile. This function is MT-safe and may be called from any thread.

gsl_hfile_pread(hfile, offset, n_bytes, bytes);

GslHFile*	hfile;	valid GslHFile
GslLong	offset;	offset in bytes within 0 and file end
GslLong	n_bytes;	number of bytes to read
gpointer	bytes;	buffer to store read bytes
RETURNS:		amount of bytes read or -1 if an error occoured (errno set)

Read a block of bytes from a GslHFile. This function is MT-safe and may be called from any thread.

gsl_hfile_zoffset(hfile);

GslHFile*	hfile;	valid GslHFile
RETURNS:		offset of first zero byte or -1

Find the offset of the first zero byte in a GslHFile. This function is MT-safe and may be called from any thread.

gsl_power2_fftac(n_values, ri_values_in, ri_values_out);

	n_values;	Number of complex values
	ri_values_in;	Complex sample values [0..n_values*2-1]
	ri_values_out;	Complex frequency values [0..n_values*2-1]

This function performs a decimation in time fourier transformation in forward direction, where the input values are equidistant sampled data, and the output values contain the frequency proportions of the input. The input and output arrays are complex values with real and imaginery portions interleaved, adressable in the range [0..2*n_values-1], where n_values must be a power of two. Frequencies are stored in-order, the K-th output corresponds to the frequency K/n_values. (If you want to interpret negative frequencies, note that the frequencies -K/n_values and (n_values-K)/n_values are equivalent). Note that the transformation is performed out of place, the input array is not modified, and may not overlap with the output array.

gsl_power2_fftar(n_values, r_values_in, ri_values_out);

	n_values;	Number of complex values
	r_values_in;	Real sample values [0..n_values-1]
	ri_values_out;	Complex frequency values [0..n_values-1]

Real valued variant of gsl_power2_fftac(), the input array contains real valued equidistant sampled data [0..n_values-1], and the output array contains the positive frequency half of the complex valued fourier transform. Note, that the complex valued fourier transform H of a purely real valued set of data, satisfies H(-f) = Conj(H(f)), where Conj() denotes the complex conjugate, so that just the positive frequency half suffices to describe the entire frequency spectrum. Even so, the resulting n_values/2 complex frequencies are one value off in storage size, but the resulting frequencies H(0) and H(n_values/2) are both real valued, so the real portion of H(n_values/2) is stored in ri_values_out[1] (the imaginery part of H(0)), so that both r_values_in and ri_values_out can be of size n_values. Note that the transformation is performed out of place, the input array is not modified, and may not overlap with the output array.

gsl_power2_fftsc(n_values, ri_values_in, ri_values_out);

	n_values;	Number of complex values
	ri_values_in;	Complex frequency values [0..n_values*2-1]
	ri_values_out;	Complex sample values [0..n_values*2-1]

This function performs a decimation in time fourier transformation in backwards direction with normalization. As such, this function represents the counterpart to gsl_power2_fftac(), that is, a value array which is transformed into the frequency domain with gsl_power2_fftac() can be reconstructed by issuing gsl_power2_fftsc() on the transform. Note that the transformation is performed out of place, the input array is not modified, and may not overlap with the output array.

gsl_power2_fftsr(n_values, ri_values_in, r_values_out);

	n_values;	Number of complex values
	ri_values_in;	Complex frequency values [0..n_values-1]
	r_values_out;	Real sample values [0..n_values-1]

Real valued variant of gsl_power2_fftsc(), counterpart to gsl_power2_fftar(), using the same frequency storage format. A real valued data set transformed into the frequency domain with gsl_power2_fftar() can be reconstructed using this function. Note that the transformation is performed out of place, the input array is not modified, and may not overlap with the output array.

gsl_rfile_close(rfile);

GslRFile*

rfile;

valid GslRFile

Close and destroy a GslRFile.

gsl_rfile_length(rfile);

GslRFile*	rfile;	valid GslRFile
RETURNS:		total length of the GslRFile in bytes

Retrieve the file length of rfile in bytes.

gsl_rfile_name(rfile);

GslRFile*	rfile;	valid GslRFile
RETURNS:		the file name used to open this file

Retrieve the file name used to open rfile.

gsl_rfile_open(file_name);

const gchar*	file_name;	name of the file to open
RETURNS:		a new opened GslRFile or NULL if an error occoured (errno set)

Open a file for reading and create a GSL read only file handle for it. The motivation for using a GslRFile over normal unix files is to reduce the amount of opened unix file descriptors by using a GslHFile for the actual IO.

gsl_rfile_position(rfile);

GslRFile*	rfile;	valid GslRFile
RETURNS:		current position within 0 and gsl_rfile_length()

Retrieve the current GslRFile seek position.

gsl_rfile_pread(rfile, offset, n_bytes, bytes);

GslRFile*	rfile;	valid GslRFile
GslLong	offset;	offset in bytes within 0 and gsl_rfile_length()
GslLong	n_bytes;	number of bytes to read
gpointer	bytes;	buffer to store read bytes
RETURNS:		amount of bytes read or -1 if an error occoured (errno set)

Read a block of bytes from a GslRFile at a specified position.

gsl_rfile_read(rfile, n_bytes, bytes);

GslRFile*	rfile;	valid GslRFile
GslLong	n_bytes;	number of bytes to read
gpointer	bytes;	buffer to store read bytes
RETURNS:		amount of bytes read or -1 if an error occoured (errno set)

Read a block of bytes from a GslRFile from the current seek position and advance the seek position.

gsl_rfile_seek_set(rfile, offset);

GslRFile*	rfile;	valid GslRFile
GslLong	offset;	new seek position within 0 and gsl_rfile_length()+1
RETURNS:		resulting position within 0 and gsl_rfile_length()+1

Set the current GslRFile seek position.

gsl_thread_awake_before(tick_stamp);

guint64

tick_stamp;

tick stamp update to trigger wakeup

Wakeup the currently running thread upon the last global tick stamp update (see gsl_tick_stamp()) that happens prior to updating the global tick stamp to tick_stamp. (If the moment of wakeup has already passed by, the thread is woken up at the next global tick stamp update.)

gsl_tick_stamp();

RETURNS:

GSL's execution tick stamp as unsigned 64bit integer

Retrieve the global GSL tick counter stamp. GSL increments its global tick stamp at certain intervals, by specific amounts (refer to bse_engine_init() for further details). The tick stamp is a non-wrapping, unsigned 64bit integer greater than 0. Threads can schedule sleep interruptions at certain tick stamps with sfi_thread_awake_after() and sfi_thread_awake_before(). Tick stamp updating occours at GSL engine block processing boundaries, so code that can guarantee to not run across those boundaries (for instance BseProcessFunc() functions) may use the macro GSL_TICK_STAMP to retrieve the current tick in a faster manner (not involving mutex locking). See also bse_module_tick_stamp(). This function is MT-safe and may be called from any thread.

gsl_tick_stamp_last();

RETURNS:

Current tick stamp and system time in micro seconds

Get the system time of the last GSL global tick stamp update. This function is MT-safe and may be called from any thread.

SEE ALSO

BSE Procedures (bse-procs(3))

Document Revised: Wed May 25 23:38:22 2005