bse-functions(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 val
ues the engine wants to process
timeout_p; Location of timeout
value
n_fds; Number of file de
scriptors 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 indi
cating 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 net
work 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 mod
ule 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 refer
ences 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 corre
sponds 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, execu
tion 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 corre
sponds 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 corre
sponds 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 corre
sponds 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 corre
sponds 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 corre
sponds 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 corre
sponds 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 corre
sponds 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 corre
sponds 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 corre
sponds to a sample precision of 24.5 bit, the average error
amounts to 7.6776048e-09. Note that there is no significant pre
cision 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 corre
sponds to a sample precision of 24.4 bit, the average error
amounts to 9.49155722e-09. Note that there is no significant pre
cision increment over bse_approx7_tanh(). On a 2GHz machine, exe
cution 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 corre
sponds 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 corre
sponds to a sample precision of 24.4 bit, the average error
amounts to 9.49141881e-09. Note that there is no significant pre
cision increment over bse_approx7_tanh(). On a 2GHz machine, exe
cution 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 er
ror < 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 approxima
tion 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 approxima
tion 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 approxima
tion 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 approxima
tion 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 gu
ranteed 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 in
volves 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 sec
onds.
RETURNS: Engine tick stamp value

Depending on the engine's sample frequency and the
time of the last global tick stamp update, calculate the corre
sponding engine tick stamp from a given system time. This func
tion is MT-safe and may be called from any thread.
bse_engine_wait_on_trans();
Wait until all pending transactions have been pro
cessed 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 in
vokations 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, suit
able for bse_idle_remove()

Queue function(data) for execution inside the main
BSE thread, similar to bse_idle_now(), albeit with a lower prior
ity. 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, suit
able 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 ref
erenced 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 fil
ter 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 pass
ing 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, ances
tors 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 ob
ject). Internal items are not stored with their parents and undo
is not recorded for internal items either. Marking containers in
ternal 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 acces
sor 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 descrip
tors to select(2) or poll(2) on
RETURNS: New job suit
able 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 func
tion to add
gpointer data; Data of timer
function
BseFreeFunc free_func; Function to
free data
RETURNS: New job suit
able 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 acces
sor 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 ordi
nary 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 to
gether 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 ordi
nary jobs have been processed. This job type should be used in
stead 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 uncon
nected 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 de
bugging 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 connect
ed 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 acces
sor 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 af
ter a node's destruction will not be executed but destroyed to
gether 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 uncon
nected 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 connect
ed 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 execut
ed). 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 con
nected 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 con
nected 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 howev
er, which may be relevant when comitting otherwise empty transac
tions 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 suit
able for bse_trans_add()

Create a new transaction job which removes a previ
ously 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 ac
cess
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 ochan
nel, 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 be
fore 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 han
dling 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 re
sumption 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 re
sumes 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 sus
pended
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-sus
pended 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 dur
ing 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 re
quired 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 BseMod
uleClass which determines the module's behaviour
gpointer user_data; user data
pointer
RETURNS: a newly cre
ated 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 corre
sponsding 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 mod
ules 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() func
tion 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 mu
table 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 ar
ray with at least proc->n_in_pspecs members
RETURNS: BseErrorType value of er
ror 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 en
tirely 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 de
rived 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 proba
bly 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 archi
tectures. 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 up
on g_object_dispose().
bse_storage_parse_item_link(self, from_item, restore_link,
data);
BseStorage* self;
BseItem* from_item; link
owner
BseStorageRestoreLink restore_link; BseStor
ageRestoreLink handler to be called once the link was resolved
gpointer data; user da
ta 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 expect
ed 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 func
tion 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 trans
action. 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 destruc
tion of all jobs currently contained in it and prevents their ex
ecution. 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 transac
tion. 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 transac
tion, collects the NULL terminated job list passed to the func
tion, 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 configura
tion
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 GslDataHan
dle
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 da
ta 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 GslDataHan
dle
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 GslData
Handle
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 co
efficients of the filter a[0..order]
const gdouble* b; pole polynomial co
efficients 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 trans
fer 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_frac
tion.
gsl_filter_tscheb2_steepness(iorder, c_freq, epsilon,
residue);
unsigned int iorder; filter order double c_freq; passband cutoff fre
quency (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 pass
band frequency (0..1)
double stopband_db; reduction in stop
band 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 rela
tive 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 func
tion 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 GslH
File. 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 fre
quency 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 inter
pret negative frequencies, note that the frequencies -K/n_values
and (n_values-K)/n_values are equivalent). Note that the trans
formation is performed out of place, the input array is not modi
fied, 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 in
put array contains real valued equidistant sampled data
[0..n_values-1], and the output array contains the positive fre
quency 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

H(n_values/2

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 recon
structed by issuing gsl_power2_fftsc() on the transform. Note
that the transformation is performed out of place, the input ar
ray 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_val
ues-1]
Real valued variant of gsl_power2_fftsc(), counter
part to gsl_power2_fftar(), using the same frequency storage for
mat. 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 nor
mal unix files is to reduce the amount of opened unix file de
scriptors 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 speci
fied 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 cur
rent 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 pri
or to updating the global tick stamp to tick_stamp. (If the mo
ment 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 un
signed 64bit integer

Retrieve the global GSL tick counter stamp. GSL in
crements 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 en
gine 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 cur
rent 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
BEAST-0.6.6-rc1 25 May 2005

BSE-Functions(3)

Copyright © 2010-2025 Platon Technologies, s.r.o.           Home | Man pages | tLDP | Documents | Utilities | About
Design by styleshout