[gmpi] Re: Topic 8 breakdown (time to focus)
- From: Chris Grigg <Chris Grigg <gmpi-public@xxxxxxxxxxxxxx>>
- To: gmpi@xxxxxxxxxxxxx
- Date: Mon, 11 Aug 2003 11:49:18 -0700
Thanks for organizing this point, Tim.
Lastly, I'd like to propose that we call the things to which I think we are
all referring 'controls' instead of 'parameters'. To my mind, anyway, it is
much easier to imagine most of these 'parameters' as knobs and switches on a
piece of hardware. 'Parameters' is a very abstract word, and is also
overloaded. If these things are not behaviorally the same as 'parameters'
in other plugin systems, let's clarify that.
First, as long as we provide an understandable working definition in
the GMPI spec, any term will work, so we shouldn't get too caught up
in this question.
Having said that, IMHO 'controls' is just as overloaded as
'parameters,' per certain Microsoft component frameworks, Mac OS GUI
widgets, etc. In other projects I've seen the term 'knobs' used,
which is semantically nice since physical front-panel knobs can be
either set statically or wiggled dynamically, and can be on either
pots, switches, or encoders... but not such a good fit once blobs,
audio buffers for analysis, etc., enter the picture.
There may not be any perfect solution for this term, and we may have
to just choose something and live with that.
Topic 8: Parameter Representation
---------------------------------
8.1) What is a 'parameter'?
Anything the plug-in wants it to be. It's just the thing that's
furnished by the host either from recorded events or live UI events
(including both computer GUIs [in-process, out-of-process, or
out-of-machine] and control surface UI), and stored in sessions.
What the plug does (or doesn't do) with them is 100% up to the
plug-in. So no need for an air-tight definition here either.
8.2) How do parameters fit into saving and restoring of a plugin's state?
It is recommended but not required that every plug publish a state
parameter. If the plug-in does provide a state parameter, the host
may use it to save/restore the plug state at any time. This parameter
will always be in blob format, but in all other respects behaves
exactly like any other parameter; the host uses the same set/get
mechanism as for any other parameter.
Internal structure/format of the state blob is solely the
responsibility of the plug-in, including management of format changes
across plug-in versions. It is recommended but not required that
restoring state via this parameter also reset the states of all other
parameters; plugs that do not support this functionality may risk
customer dissatisfaction...
If this mechanism is supported, then there is no need for a separate
state save/restore mechanism elsewhere in the GMPI API.
One variation on this mechanism would be to reserve a particular
parameter index for the state parameter. Since state save/restore is
almost universally needed, index 0 might be a logical choice for
this. However support of the state parameter is always optional;
plug-ins not supporting it can simply return a null pointer and/or 0
length in response to a gmpi_getParameter( 0 ), and ignore
gmpi_setParameter( 0 ).
8.3) What data types can be used for parameters?
...
8.6) Do parameters use normalized or natural ranges?
Logical data types for parameters are indicated by an enum defined in
the GMPI spec. For GMPI 1.0 the enum would include at a minimum:
enum, integer, real, and blob. Text may also be useful.
The valid data range for parameter is specified in a manner that
depends on the logical data type:
- For enum parameters: A list of valid integer values, with a text
tag for each provided value (these tags may be used in configuring
UIs)
- For integer parameters: A minimum value, and a maximum value, both signed
- For real parameters: A minimum value, a maximum value, both signed,
perhaps plus some indication of resolution/granularity (... though
that gets hairy fast)
- For blobs: A maximum length in bytes
8.3) How are parameters identified within a plugin? (e.g. by index,
by name, etc.)
8.4) How are a plugin's parameters discovered by the host?
8.5) How are properties of a parameter discovered by the host? (e.g. type,
range, etc.)
8.7) Is there a heirarchy of parameters, or is there a single per-plugin
namespace?
At discovery time (which may recur during the plug-in instance's
lifetime, and may not be the same as instantiation time or
initialization time) the host calls short gmpi_getParameterCount(
void ), then iterates paramDescr* gmpi_getParameterDescription( short
inParamIndex ) on the returned count. The parameter indexes must
therefore start out asa contiguous range of integers.
Each returned paramDescr contains a name, an index, a label, a
logical data type, and a valid data range for the indicated
parameter. The name may reflect hierarchical groupings, using
slash-delimited path syntax. The label is intended for use in a
generic GUI, and may not necessarily be unique for the plug (imagine
a synth with two LFos -- each could use the label 'Rate'). Logical
data type and range are as described above.
During ordinary processing operation, the main parameter set & get
methods access parameters only by index, not name, for
speed/simplicity.
The plug-in must also implement the conversion functions string
gmpi_getParameterName( short inParamIndex ), string
gmpi_getParameterLabel( short inParamIndex ), and short
gmpi_getParameterIndexFromName( string inParamName ).
8.8) Can the parameter list change dynamically? How?
Yes.
In the general case there are three ways to change any list: Change
an item in place, add a new item, delete an existing item.
Delete a parameter: The plug-in notifies the host via
gmpiHost_parameterDeleted( plugInstance inPlug, short inParamIndex
). That parameter index is retired for the life of the plug-in
instance, meaning the host should not use it any more, and plug will
return an error on subsequent attempts to set or get that parameter
index.
Add a parameter: The plug-in notifies the host via
gmpiHost_parameterAdded( plugInstance inPlug, paramDescr&
inParamDescr ). The parameter index in the paramDescr must be the
next available index, and not previously used for this plug instance.
Change a parameter: The plug-in notifies the host via
gmpiHost_parameterDescriptionChanged( plugInstance inPlug,
paramDescr& inParamDescr ). The parameter index in the paramDescr
must match an existing parameter, however any of the other fields can
change. (There should be a rule for what to do if the current
parameter type and/or value is invalidated by the new paramDescr.)
(It may be possible to combine the functionality of *Added*() &
*Changed*(), but I'm not sure the semantics would be as clear.)
If there are use cases where dynamic changes of the parameter list
should be made available to the host, then add to the plug-in API the
following:
- gmpi_deleteParameter( shortinParamIndex )
- gmpi_addParameter( paramDescr& inParamDescr )
- gmpi_changeParameter( paramDescr& inParamDescr )
8.9) Are parameters the things that the user automates? Are all parameters
automatable?
Yes and yes.
8.10) Is there a distinction between a time-varying parameter and a
non-time-varying parameter? Is this a fixed characteristic, or can it
be changed?
-- I still don't understand this question - can we get clarification?
Any parameter may be changed at any time. Plugs are free to ignore
any particular parameter change event,but only at their own risk of
customer dissatisfaction...
(Though if anyone has an argument that there should be
initialization-time-only parameters, I'm open to hearing it.)
-- Chris G.
..end..
----------------------------------------------------------------------
Generalized Music Plugin Interface (GMPI) public discussion list
Participation in this list is contingent upon your abiding by the
following rules: Please stay on topic. You are responsible for your own
words. Please respect your fellow subscribers. Please do not
redistribute anyone else's words without their permission.
Archive: //www.freelists.org/archives/gmpi
Email gmpi-request@xxxxxxxxxxxxx w/ subject "unsubscribe" to unsubscribe
Other related posts:
