KL2DFG Command line utility

kl2dfg is a command line executable which allows to generate Canvas preset files for a given KL extension. If successful, it creates a log file called kl2dfg.log in the destination folder which lists the complete process. To use the resulting presets in Canvas the target folder has to be on the FABRIC_DFG_PATH environment variable. Alternatively you can also specify a subfolder for an extension to provide Canvas presets using the dfgPresets member. Please see The Extension Manifest File for more information.

To try out KL2DFG, simply open a shell using the Fabric environment variables (see Installing the Fabric Engine license), and type

kl2dfg

Result:

kl2dfg can be used to generate preset files out of KL extensions.
For more options use kl2dfg --help

kl2dfg supports a series of options, which can be obtained by running kl2dfg with the help flag

kl2dfg --help

Result:

kl2dfg can be used to generate preset files out of KL extensions.

Usage:    kl2dfg [options] FPMFILE OUTPUTDIR
Example:  kl2dfg Math.fpm.json /temp/presets/Math

Valid options:
  -list                 Lists all of the valid doxygen qualifiers.
  -inheritance          Enables inheritance for generated presets.
  -polyThis             Enables polymorphism with respect to 'this' for generated presets.
  -polyParams           Enables polymorphism with respect to parameters for generated presets.
  -genAllArrays         Automatically generates all array presets.
  -addExecutePort       Automatically adds a leading execute port for all presets.
  -polyThisInTypeDir    Place 'polyThis' presets in type directory.
  -noPolyThisInFuncDir  Do not place 'polyThis' presets in 'Func' directory.

Available options:

list

Presents the user with a list of doxygen modifiers which can be used to drive kl2dfg’s behavior. Doxygen qualifiers can be used inside the doxygen style comments of a function. For example:

/// \dfgPresetTitle MyPresetName
function Boolean someFunction(Scalar a)

Will cause kl2dfg to pick a different name for the preset than the name of the function. For a full list of qualifiers please use the list flag.

kl2dfg -list

Result:

kl2dfg can be used to generate preset files out of KL extensions.

The kl code can be annotated within doxygen style comments to control
kl2dfg's behavior. Find a list of doxygen qualifiers below:

\dfgPresetCreate
Forces creation of preset

\dfgPresetOmit
Avoids creation of preset, obsolete if function also has \internal

\dfgPresetGUID "GUID"
Use the specified GUID instead of automatically generating one

\dfgPresetTitle "title"
Overrides the title of the preset

\dfgPresetFolder "myFolder"
Relative path for the folder to use for the preset

\dfgPresetCacheRule "Never"
Sets up the cache rule to use for the preset

\dfgPresetColor Color(255, 0, 0)
Overdrives the preset body + header color

\dfgPresetHeaderColor Color(0, 255, 0)
Overdrives just the preset header color, can be combined with dfgPresetColor

\dfgPresetTextColor Color(0, 255, 0)
Overdrives the color of the text inside the node

\dfgPresetDefault port Value
Sets up the default value to use for a given input port

\dfgPresetType port Type
Overrides the KL port type a given input port

\dfgReturnIfNull
If specified, the function preset will return if the object calling the function is null 

\dfgThrowExceptionIfNull
If specified, the function preset will throw an exception if the object calling the function is null 

\dfgPresetRange port (0.0, 1.0)
Defines the range to use for sliders, works with Floats and Integers

\dfgPresetCombo port ("label1", "label2", ...)
Enables the use of a combo box in the ui, works for Integers and Strings

\dfgPresetHidden port true
Hides a given port from the UI when editing a node (or shows it if set to false)

\dfgPresetTooltip
  My elaborate tooltip description for the node.
\enddfgPresetTooltip
Shows a tooltip on the node. If this isn't provided the plain text in the comment
above the function will be used for the tooltip.

\dfgCollapsedState state
Sets the default collapsed state for a node. Can be 0, 1 or 2.

\dfgDocUrl http:///www.mydomain.com/docs/mydoc.html
Sets up documentation links for the generated nodes.

\dfgAlwaysShowDaisyChainPorts true
Ensures that the daisy chain ports on the right of input ports are always shown.

\dfgCreateArrayPreset
If specified the array presets for the given type / function will be generated. This is independent of the -genAllArrays command line flag.

\dfgUseInheritance
If specified on a KL type (struct or object) all inherited methods will also be generated as presets. This is independent of the -inheritance command line flag.

\dfgAddExecutePort
If specified the function preset will contain an execute port, which allows to daisy chain functions. This is independent of the -addExecutePort command line flag

\dfgArrayPexMargin 10000
The margin used when switching from a linear loop to pex in array presets.

\dfgArrayPexDisable
If true disables the pex calls.

Examples:

Exts/Math/RotationOrder.kl
Exts/Math/RotationOrder/RotationOrder.canvas
Exts/Geometry/PolygonMesh/AddTeapot.canvas

polyThis

kl2dfg will generate only one preset for methods with the same notation within an extension, with respect to a common “this” type (or return type, in the case of functions). For example:

function SInt32 Vec3.getMySum() { ... }

function SInt32 Vec4.getMySum() { ... }

Would result in only one Canvas preset file, called Func.getMySum instead of two separate presets for Vec3 and Vec4.

Note

You can find more information about the consequences of polymorphism here: Polymorphic nodes.

polyParams

kl2dfg will generate only one preset for methods with the same notation within an extension, with respect to parameter types. For example:

function SInt32 MyType.someFunc(Integer x) { ... }

function SInt32 MyType.someFunc(Float32 x) { ... }

Would result in one Canvas preset file, called MyType.someFunc, that has a polymorphic type for the first parameter.

Note

You can find more information about the consequences of polymorphism here: Polymorphic nodes.

inheritance

Enables the generation of presets for inherited methods. For example:

interface i {
  String getName();
};

object a : i {
  SInt32 index;
};

function a.getName() {
  return 'a'+this.index;
}

object b : a {
};

function b.reportSomething() {
  report('something');
}

Without inheritance the presets generated would be:

a.getName
b.reportSomething

With inheritance enabled the presets generated would be:

a.getName
b.getName
b.reportSomething

can also enable this functionality on a per preset basis by using the dfgUseInheritance doxygen qualifier.

genAllArrays

Enables the generation of array presets for given methods. This makes working with arrays inside of Canvas much easier. You can also enable this functionality on a per preset basis by using the dfgCreateArrayPreset doxygen qualifier.

Note

This functionality might be deprecated in future version of kl2dfg.

addExecutePort

Note

This option is deprecated, since as of version 2.2.0 all instance nodes in Canvas automatically have a first Execute port called ‘exec’.

For easier daisy chaining of Canvas presets kl2dfg supports to add an extra port as the first port of any Canvas preset. You can also enable this functionality on a per preset basis by using the dfgAddExecutePort doxygen qualifier.

polyThisInTypeDir

By default, presets that are polymorphic in ‘this’ will only be placed in the generic ‘Func’ subdirectory of the target directory. Using this flag will also place them in the type directory for each type for which ‘this’ applies.

noPolyThisInFuncDir

By default, presets that are polymorphic in ‘this’ will be placed in the generic ‘Func’ subdirectory of the target directory. Using this flag will disable this behaviour.

Example

Generating all math presets in a temporary location:

kl2dfg $FABRIC_DIR/Exts/Builtin/Math/Math.fpm.json $TEMP

Result:

Error: LogFile '$TEMP/kl2dfg.log' could not be created for writing.