NAME
Rivl_ConfigureSignal, Rivl_QuerySignal, Rivl_SignalSize, Rivl_SignalType -
query and configure a signal's properties
SYNOPSIS
#include <rivl.h>
void
Rivl_ConfigureSignal ()
void
Rivl_QuerySignal ()
Rivl_Point
Rivl_SignalSize (signal)
Rivl_ValueType
Rivl_SignalType (signal)
ARGUMENTS
- Rivl_Signal signal (in)
-
The signal to query or configure.
DESCRIPTION
Rivl_ConfigureSignal sets the values of one or more properties of signal.
The arguments following signal come in pairs: a string giving the
property name, and a value of the appropriate type for that property.
The list of pairs must be terminated with a single NULL pointer.
Rivl_QuerySignal queries the values of one or more properties of
signal. The arguments following signal come in pairs: a string giving
the property name, and a pointer to an object of the appropriate type
for that property. The value of each specified property is returned in
the provided pointer. The list of pairs must be terminated with a
single NULL pointer.
Rivl_SignalSize and Rivl_SignalType are shortcuts for querying two
frequently accessed properties, size and type. Each returns the value
of its property.
When a new signal is created by Rivl_AddNode, its properties are
set to default values. There are two sets of defaults: one for leaf
node signals (those with no inputs), and one for non-leaf node signals
(those with at least one input). Just after Rivl_AddNode, you can
call Rivl_ConfigureSignal to override any of the default values.
Signal properties are meant to be non-deterministic. If a property of
a signal is queried twice at different times, it should yield the same
value. To maintain this property, you should only call
Rivl_ConfigureSignal when no one has yet accessed the specified
property in that signal (such as right after a Rivl_AddNode). The
safe, non-destructive way to set a signal's property is to duplicate
the signal with Rivl_DupSignal and then configure and return the
duplicate.
The properties are listed below. Each description begins with
the following information:
- Name: The case-sensitive name used to refer to the property
when configuring or querying its value.
- C type: The C type of the property. A value of this type must be
passed when configuring the property, and a pointer to this type must
be passed when querying the property.
- Leaf Default: The default value given to leaf signals. "No
default" means that the property must be configured with a value by
the caller if that property is appropriate to the signal. For example,
there is no default for matte, so this property must be configured
for image and audio signals.
- Non-leaf Default: The default value given to non-leaf signals. "From
last input" means that the value is taken from the last-numbered input
(for example, the second input in a two-input node).
INTERNAL PROPERTIES
Internal properties are controlled by Rivl and contain information
essential to the proper functioning of the system. Users should not
change internal properties from Tcl.
- Name: type
- C Type: Rivl_ValueType
- Leaf Default: No default
- Non-leaf Default: From last input
- The type of value obtained by sampling the signal. See value types.
- Name: mediaType
- C Type: Rivl_MediaType
- Leaf Default: RIVL_SIG
- Non-leaf Default: From last input
- Indicates whether the signal is an image, sequence, audio, or plain
signal. See media types.
- Name: haveRes
- C Type: Rivl_Point
- Leaf Default: 1.0
- Non-leaf Default: Maximum of inputs.
- This property contains an upper bound on the sample rate at which
the signal yields unique values. Each dimension has its own value.
The haveRes may be used to prune unnecessary computation. For example,
if we are computing a range of a video sequence signal at 60 frames
per second, and the haveRes of the signal is 24.0, then we could
compute just 24 frames per second and scale up the results. It is
permissible for haveRes to be overestimated or even set to infinity -
this just decreases the opportunity for optimization. However, the
haveRes must not be underestimated or Rivl may fail to compute valid
data.
- Name: protoImage
- C Type: Rivl_Signal
- Leaf Default: No default
- Non-leaf Default: From last input
- Only used by sequences. This property records the image type and
image size of a sequence's images in the form of a blank image. Its
value is consulted by commands like seq_imsize and seq_imtype. In
addition, when a sequence's images are extracted, they are conformed
to the size and type of the sequence's protoImage; see
Rivl_SeqResolveImage.
EXTERNAL PROPERTIES
External properties are used to record semantic information in signals
and to provide communication between the user and certain system
commands. The user is primarily responsible for maintaining the values
of external properties. Where built-in system commands initialize or
modify external properties, this behavior is documented and
predictable.
The commands sig_set and sig_configure provide a generic interface to
Rivl_ConfigureSignal for external properties. sig_set duplicates the
signal first. The command sig_query provides a generic interface to
Rivl_QuerySignal for external properties.
Name: size
C Type: Rivl_Point.
Leaf Default: No default
Non-leaf Default: From last input
This property holds the user notion of size of signal and output
size. It is accessed by sig_size and set by sig_setsize. It affects
the behavior of commands like im_write and im_display.
Name: outputRate
C Type: double
Leaf Default: 1.0
Non-leaf Default: Maximum of inputs.
Currently used only by sequences. This property holds the user
notion of the sample rate and output rate. It is accessed by
seq_fps and set by seq_setfps. It affects the behavior of commands
like seq_write and seq_to_ims.
Name: matte
C Type: Rivl_Signal
Leaf Default: No default
Non-leaf Default: From last input
Used by images and audio. This property points to a gray-level
signal that indicates the transparency of each value. It is accessed
by im_matte and set by im_setMatte. In addition, geometric commands
like im_trans and im_scale transform the matte along with the
image. The matte is fundamental to im_overlay.