<!--
Software License :
Copyright (c) 2004, The Open Effects Assocation Ltd. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name The Open Effects Association Ltd, nor the names of its
contributors may be used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-->
<!--
DTD for the XML resource file of an OFX image effect plugin.
Author Bruno Nicoletti
Each ofx binary may have a single xml file associated with it that is contains resource overrides for various properties of the plugin. This file is the DTD for those resource files. Typically, the properties being changed are to do with user interface labels and layouts, as well as a few other things such as default values for parameters and so on.
If an element in the DTD has an equivilant property in OFX, the element will be the named with the same string that labels the property in the binary. For example the default property is labelled with "OfxParamPropDefault" in both cases.
The only attributes used on any element are there to identify the element, typically to associate it with a named object in the binary. This is the 'name' attribute. The only other attributes are to associate a host and a locale with the resource set.
The root element is 'OfxImageEffectResource'.
As each binary contains one or more plug-ins, the resource file contains overrides for multiple plug-ins. This is the 'OfxPlugin' element. The 'name' attribute of each must correspond to a OfxPlugin::pluginIdentifier string found in the binary.
Each plug-in can have multiple resources respecifications. This is the 'OfxResourceSet'. Each resource set has an 'ofxHost' and 'ofxLocale' attribute. These specify which host application and which locale the resource set applies to. This allows for internationalisation and per host tuning. Either or both of these can be set to the value 'default', which acts as a catch all case. For example to change all the labels to a specific locale, have a resource set with the host set to 'default' and the locale to the given one.
A resource set is made up of one more 'OfxImageEffectContext' elements, as well as the labels for the plug-in itself and message redefinitions. The 'name' attribute of a context corresponds to one of the context that the plugin declared itself valid for, or 'default'. You can thus redefine properties on a per context basis, with a catch all default case.
A message redefinition is associated with the 'messageId' passed into the OfxMessageSuite::message function. The CDATA value is the new value of the message.
A resource set is made up of parameter redefinitions, clip redefinitions, parameter hierarchy redefinitions and parameter page set redefinitions.
Any parameter (except page and hierachy params) in the binaray may have certain properties overridden. Each parameter type has a corresponding element, for example the 2D integer parameter is specified via the 'OfxParamTypeInteger2D', the choice parameter by the 'OfxParamTypeChoice' element. There are 13 different elements, each of which corresponds to an OFX parameter type. The 'name' attribute of a parameter element is used to associate it with a specific parameter in the binary.
Each parameter element has it's own specific set of sub elements, as not all parameters support all properties.
An image effect clip may simply have its labels and hints overridden. This is the 'OfxImageClip' element. It is associated with a clip in the binary via its 'name' element.
An 'OfxParamHierarchy' element is used to redefine the hierarchical ordering of parameters. A parameter can only occur once in this hierarchy. If a hierarchy is encountered, then it will completely redefine any hierarchy defined in the binary. It is fairly straight forward. It allows for the definition of new grouping parameters. This must be reflected in the structures created in the plug-in.
The 'OfxParamPageSet' element is used to define paged layouts of parameters. If present, it will completely redefine all paged layouts for the given context. It consists of one or more 'OfxParamPage' elements, which can be labelled. The order of pages in any user interface is the same as encountered in the resource file. As parameters are added to the page, they appear in any interface at the top left and are added top down, left to right. The two dummy position skipping parameters, "OfxParamPageSkipRow" and "OfxParamPageSkipColumn" can be used to control where in the page parameters are added.
Because of the ability to 'default' hosts, locales and contexts, there is potentially ambiguity as to what property applies in which case, as the same property may be set in more that one valid location. In order of precedence, a property has its value set from the resource file if a match is found according to...
- exact locale, exact host, exact context
- exact locale, exact host, default context
- exact locale, default host, exact context
- exact locale, default host, default context
- default locale, exact host, exact context
- default locale, exact host, default context
- default locale, default host, exact context
- default locale, default host, default context
Otherwise its value is that found in the binary.
Parameters and clips can have their properties set in the 'default' context, even if they do not appear in all contexts.
You cannot set the page layout or the parameter hierarchy in the default context.
In summary, a rough hierarchy of elements is below. '+' means one or more, '*' means zero or more, '?' means zero or one.
OfxImageEffectResource
- OfxPlugin+ 'name'
- OfxResourceSet+ 'ofxHost' 'ofxLocale'
- OfxImageEffectContext+ 'name'
- parameter redefinitions*
- clip redefinitions*
- OfxParamHierarchy
- OfxParam*
- OfxParamGroup*
- OfxParam
- OfxParamGroup*
- OfxParamPageSet?
- OfxParamPage+
- OfxParam+
The 'base' level elements used to set property values come in several varieties, bool, int, double and string. These are used in situations where the an element can have more than one 'type' or is not a simple string value. For example the OfxParamPropDefault element for a parameter can be int, double or string, of 1, 2 or 3 dimensions, whilst the OfxPropLabel element is always a string. Int, double and string come in 2 and 3 dimensional varieties.
For the non simple base element, their values can be....
Bool has 'true', 'false', 'TRUE', 'FALSE', '0' and '1' as acceptable values.
Legal values for integers correspond to the standard C library function 'strtol' syntax.
Legal values for doubles are specified by the standard C library function 'strtod' syntax.
String values must be enclosed in double quotes ie, '"'. To use a double quote in a string, escape it with a backslash character.
Multiple dimensional values are simply separated by white space.
Examples...
<bool> FALSE </bool>
<int> 1 </int>
<string3> "tom" "dick" "harry" </string3>
Errors should be handled robustly. If a respecified parameter doesn't exist in the binary, or it doesn't have a certain property, the host should not fail on that XML file.
-->
<!DOCTYPE OfxImageEffectResource [
<!ELEMENT OfxImageEffectResource (OfxPlugin+)>
<!ELEMENT OfxPlugin (OfxResourceSet+)>
<!ATTLIST OfxPlugin name CDATA "">
<!ELEMENT OfxResourceSet (OfxImageEffectContext+, OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxImageEffectPluginPropGrouping?, OfxMessage* ) >
<!ATTLIST OfxResourceSet ofxHost CDATA "default">
<!ATTLIST OfxResourceSet ofxLocale CDATA "default">
<!ELEMENT OfxMessage ( CDATA )>
<!ATTLIST OfxMessage name CDATA "">
<!ELEMENT OfxImageEffectContext (OfxImageClip*, OfxParamPageSet?, OfxParamHierarchy?, OfxParamTypeInteger*, OfxParamTypeDouble*, OfxParamTypeBoolean*, OfxParamTypeChoice*, OfxParamTypeRGBA*, OfxParamTypeRGB*, OfxParamTypeDouble2D*, OfxParamTypeDouble3D*, OfxParamTypeInteger2D*, OfxParamTypeInteger3D*, OfxParamTypeString*, OfxParamTypeCustom*, OfxParamTypePushButton*) >
<!ATTLIST OfxImageEffectContext name CDATA "default">
<!ELEMENT OfxParamHierarchy (OfxParam*, OfxParamGroup*)>
<!ELEMENT OfxParam ( EMPTY )>
<!ATTLIST OfxParam name CDATA "">
<!ELEMENT OfxParamGroup (OfxPropLabel, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParam*, OfxParamGroup*)>
<!ELEMENT OfxImageClip ((OfxPropLabel, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropHint?)>
<!ATTLIST OfxImageClip name CDATA "">
<!ELEMENT OfxParamPageSet (OfxParamPage+)>
<!ELEMENT OfxParamPage (OfxPropLabel, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropHint?, OfxParam+)>
<!ELEMENT OfxParamTypeInteger (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropAnimates?, OfxParamPropEvaluateOnChange?, OfxParamPropPersistant?, OfxParamPropSecret?, OfxParamPropScriptName?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParamPropMin?, OfxParamPropMax?, OfxParamPropDisplayMin?, OfxParamPropDisplayMax?, OfxParamPropDefault?)>
<!ATTLIST OfxParamTypeInteger name CDATA "">
<!-- If you are not redefining the hierarchy, you can relabel a group param -->
<!ELEMENT OfxParamTypeGroup (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?)>
<!ATTLIST OfxParamTypeGroup name CDATA "">
<!-- If you are not redefining the page layout, you can relabel a page param -->
<!ELEMENT OfxParamTypePage (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?)>
<!ATTLIST OfxParamTypePage name CDATA "">
<!ELEMENT OfxParamTypeInteger2D (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropAnimates?, OfxParamPropEvaluateOnChange?, OfxParamPropPersistant?, OfxParamPropSecret?, OfxParamPropScriptName?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParamPropMin?, OfxParamPropMax?, OfxParamPropDisplayMin?, OfxParamPropDisplayMax?, OfxParamPropDefault?, OfxParamPropDimensionLabel?)>
<!ATTLIST OfxParamTypeInteger2D name CDATA "">
<!ELEMENT OfxParamTypeInteger3D (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropAnimates?, OfxParamPropEvaluateOnChange?, OfxParamPropPersistant?, OfxParamPropSecret?, OfxParamPropScriptName?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParamPropMin?, OfxParamPropMax?, OfxParamPropDisplayMin?, OfxParamPropDisplayMax?, OfxParamPropDefault?, OfxParamPropDimensionLabel?)>
<!ATTLIST OfxParamTypeInteger3D name CDATA "">
<!ELEMENT OfxParamTypeDouble (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropAnimates?, OfxParamPropEvaluateOnChange?, OfxParamPropPersistant?, OfxParamPropSecret?, OfxParamPropScriptName?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParamPropMin?, OfxParamPropMax?, OfxParamPropDisplayMin?, OfxParamPropDisplayMax?, OfxParamPropDefault?, kOfxParamPropDoubleType?, OfxParamPropDigits?, OfxParamPropShowTimeMarker?)>
<!ATTLIST OfxParamTypeDouble name CDATA "">
<!ELEMENT OfxParamTypeDouble2D (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropAnimates?, OfxParamPropEvaluateOnChange?, OfxParamPropPersistant?, OfxParamPropSecret?, OfxParamPropScriptName?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParamPropMin?, OfxParamPropMax?, OfxParamPropDisplayMin?, OfxParamPropDisplayMax?, OfxParamPropDefault?, kOfxParamPropDoubleType?, OfxParamPropDigits?, OfxParamPropShowTimeMarker?, OfxParamPropDimensionLabel?)>
<!ATTLIST OfxParamTypeDouble2D name CDATA "">
<!ELEMENT OfxParamTypeDouble3D (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropAnimates?, OfxParamPropEvaluateOnChange?, OfxParamPropPersistant?, OfxParamPropSecret?, OfxParamPropScriptName?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParamPropMin?, OfxParamPropMax?, OfxParamPropDisplayMin?, OfxParamPropDisplayMax?, OfxParamPropDefault?, kOfxParamPropDoubleType?, OfxParamPropDigits?, OfxParamPropShowTimeMarker?, OfxParamPropDimensionLabel?)>
<!ATTLIST OfxParamTypeDouble3D name CDATA "">
<!ELEMENT OfxParamTypeBoolean (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropAnimates?, OfxParamPropEvaluateOnChange?, OfxParamPropPersistant?, OfxParamPropSecret?, OfxParamPropScriptName?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParamPropDefault?)>
<!ATTLIST OfxParamTypeBoolean name CDATA "">
<!ELEMENT OfxParamTypeChoice (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropAnimates?, OfxParamPropEvaluateOnChange?, OfxParamPropPersistant?, OfxParamPropSecret?, OfxParamPropScriptName?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParamPropDefault?, OfxParamPropChoiceOption?)>
<!ATTLIST OfxParamTypeChoice name CDATA "">
<!ELEMENT OfxParamTypeRGB (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropAnimates?, OfxParamPropEvaluateOnChange?, OfxParamPropPersistant?, OfxParamPropSecret?, OfxParamPropScriptName?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParamPropMin?, OfxParamPropMax?, OfxParamPropDisplayMin?, OfxParamPropDisplayMax?, OfxParamPropDefault?)>
<!ATTLIST OfxParamTypeRGB name CDATA "">
<!ELEMENT OfxParamTypeRGBA (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropAnimates?, OfxParamPropEvaluateOnChange?, OfxParamPropPersistant?, OfxParamPropSecret?, OfxParamPropScriptName?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParamPropMin?, OfxParamPropMax?, OfxParamPropDisplayMin?, OfxParamPropDisplayMax?, OfxParamPropDefault?)>
<!ATTLIST OfxParamTypeRGBA name CDATA "">
<!ELEMENT OfxParamTypeString (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropAnimates?, OfxParamPropEvaluateOnChange?, OfxParamPropPersistant?, OfxParamPropSecret?, OfxParamPropScriptName?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParamPropDefault?)>
<!ATTLIST OfxParamTypeString name CDATA "">
<!ELEMENT OfxParamTypeCustom (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropAnimates?, OfxParamPropEvaluateOnChange?, OfxParamPropPersistant?, OfxParamPropSecret?, OfxParamPropScriptName?, OfxParamPropHint?, OfxParamPropEnabled?, OfxParamPropDefault?)>
<!ATTLIST OfxParamTypeCustom name CDATA "">
<!ELEMENT OfxParamTypePushButton (OfxPropLabel?, OfxPropShortLabel?, OfxPropLongLabel?, OfxParamPropInteractSizeAspect?, OfxParamPropInteractMinimumSize?, OfxParamPropInteractPreferedSize?, OfxParamPropSecret?, OfxParamPropHint?, OfxParamPropEnabled?)>
<!ATTLIST OfxParamTypePushButton name CDATA "">
<!ELEMENT OfxPropLabel (CDATA)>
<!ELEMENT OfxPropShortLabel (CDATA)>
<!ELEMENT OfxPropLongLabel (CDATA)>
<!ELEMENT OfxImageEffectPluginPropGrouping (CDATA)>
<!ELEMENT OfxParamPropInteractSizeAspect (double)>
<!ELEMENT OfxParamPropInteractMinimumSize (int2)>
<!ELEMENT OfxParamPropInteractPreferedSize (int2)>
<!ELEMENT OfxParamPropAnimates (bool)>
<!ELEMENT OfxParamPropEvaluateOnChange (bool)>
<!ELEMENT OfxParamPropPersistant (bool)>
<!ELEMENT OfxParamPropSecret (bool)>
<!ELEMENT OfxParamPropScriptName (CDATA)>
<!ELEMENT OfxParamPropHint (CDATA)>
<!ELEMENT OfxParamPropDoubleType (CDATA)>
<!ELEMENT OfxParamPropEnabled (bool)>
<!ELEMENT OfxParamPropChoiceOption (string*)>
<!ELEMENT OfxParamPropShowTimeMarker (bool)>
<!ELEMENT OfxParamPropIncrement (double)>
<!ELEMENT OfxParamPropDigits (int)>
<!ELEMENT OfxParamPropDimensionLabel (string2?, string3?)>
<!ELEMENT OfxParamPropStringMode (CDATA)>
<!ELEMENT OfxParamPropMin (int?, int2?, int3?, double?, double2?, double3?, double4?)>
<!ELEMENT OfxParamPropMax (int?, int2?, int3?, double?, double2?, double3?, double4?)>
<!ELEMENT OfxParamPropDisplayMin (int?, int2?, int3?, double?, double2?, double3?, double4?)>
<!ELEMENT OfxParamPropDisplayMax (int?, int2?, int3?, double?, double2?, double3?, double4?)>
<!ELEMENT OfxParamPropDefault (int?, int2?, int3?, double?, double2?, double3?, double4?, bool?, string?)>
<!ELEMENT bool (CDATA)>
<!ELEMENT int (CDATA)>
<!ELEMENT int2 (CDATA)>
<!ELEMENT int3 (CDATA)>
<!ELEMENT double (CDATA)>
<!ELEMENT double2 (CDATA)>
<!ELEMENT double3 (CDATA)>
<!ELEMENT double4 (CDATA)>
<!ELEMENT string (CDATA)>
<!ELEMENT string2 (CDATA)>
<!ELEMENT string3 (CDATA)>
]
>
