[[PageOutline(1-4, Chapter Overview)]] || [wiki:Tutorial/OpenSG2/Memleak << Previous Chapter: Find Memory leaks] || [wiki:Tutorial Tutorial Overview] || [wiki:Tutorial/OpenSG2/NewContainerType Next Chapter: Creating new container types >>] || ----- = fcd2code - OpenSG 2 code generator = fcd2code is a python script that generates C++ code and headers from an input Field Container Description (.fcd) file. These files contain xml-like text descriptions of a single OpenSG container type and its member fields. == Usage == {{{ Usage: fcd2code [options] Options: -h, --help show this help message and exit -d file.fcd, --fcd-file=file.fcd !FieldContainer description file. -b, --write-base write the Base files. [default: false]. -f, --write-fc write the User files. [default: false]. -p PATH, --out-path=PATH destination path for files. -r PATH, --root-path=PATH root of the OpenSG source tree. -t PATH, --template-path=PATH path to where the fcd2code templates are stored. -v, --verbose print diagnostic messages. [default: false]. -c, --compat-mode enable 1.x compatibility mode. [default: false]. -B, --bundle create field bundle. [default: false]. }}} == Options == `-d file.fcd, --fcd-file=file.fcd` Field container description file (.fcd) to use as input for code generation. `-b, --write-base` Writes the Base files (see [wiki:Tutorial/OpenSG2/Fcd2Code#Description Description] below) for the container. `-f, --write-fc` Writes the User files (see [wiki:Tutorial/OpenSG2/Fcd2Code#Description Description] below) for the container. '''Note:''' Be very careful with this option, it will overwrite any changes you have made to the user files! `-p PATH, --out-path=PATH` Directory where to put output files, by default the current directory is used. `-r PATH, --root-path=PATH` Path to the root directory (the one container the Source and Tools directories) of the OpenSG source tree. This is used to locate the template files for the generated code, see also --template-path. `-t PATH, --template-path=PATH` Path to the directory containing the template files for the generated code. This is an alternative when you don't have an OpenSG source tree, the template files are usually installed in /bin/fcd2code/. `-v, --verbose` Enable verbose messages. Can be helpful when fcd2code aborts processing because of a misspelled element in the .fcd file. `-c, --compat-mode` Enables a compatibility mode that generates additional member functions that can simplify porting of OpenSG 1.x applications. These functions are surrounded by `#ifdef OSG_1_COMPAT`, so they will only be available if you set the cmake variable `OSGCOMPAT_ENABLE` to `ON`. `-B, --bundle` Obsolete, do not use. == Description == fcd2code is a python script that generates C++ code and headers from an input .fcd file. These files contain xml-like text descriptions of a single OpenSG container type and its member fields. For every container there are two sets of source files: || Base files: || User files: || || || || || OSG{Name}Base.h || OSG{Name}.h || || OSG{Name}Base.inl || OSG{Name}.inl || || OSG{Name}Base.cpp || OSG{Name}.cpp || || OSG{Name}Fields.h || || The Base files are always fully generated by fcd2code and should never be modified by hand as changes to the internals of OpenSG may require them to be regenerated at any point. The User files on the other hand are only initially generated by fcd2code and code has to be added to them to give the container any interesting functionality (the OpenSG basics like synchronization are functional, the container just won't do anything besides storing data in its fields). == .fcd file format == A Field Container Description file (.fcd) is an xml-like text file. There are only two types of tags allowed: `` and `` and there may only be one `` tag per file and all `` tags must be inside it. All important information is stored in attributes of these tags (see below). {{{ Description of the container Description of the first field. Description of the second field. }}} In the following descriptions a type for the different attributes is mentioned, but since the .fcd files are xml-like attributes are always strings, the type is only used to give an idea what values are accepted: bool:: only `true` and `false` enum:: one value from a limited set of possibilities, the possible values are listed in the description of the attribute string:: any value, but often the name of type or file === tag === ''name'' (string):: Name of the container, also determines the names of generated ''parent'' (string):: Name of the parent type, must be !FieldContainer or a derived type ''mixinparent'' (string):: ''mixinheader'' (string):: Header file that defines mixinparent ''library'' (string):: The library (e.g. OSGDrawable) this container belongs to ''systemcomponent'' (bool):: Whether this type is part of OpenSG, that is whether it lives inside the OpenSG source tree (if it is false `#include` statements are generated to include OpenSG headers from an installed OpenSG) ''parentsystemcomponent'' (bool):: Whether the parent type is part of OpenSG ''structure'' (enum):: - `abstract` an abstract type that can not be instantiated - `concrete` a concrete type that can be instantiated ''decoratable'' (bool):: Whether this type supports the decorator pattern ''group'' (string):: ''namespace'' (string):: ''libnamespace'' (string):: ''fieldsUnmarkedOnCreate'' (string):: ''decorateeFieldFlags'' (string):: ''pointerfieldtypes'' (enum):: - `single`: generate only single fields that can store pointers to this type - `multi`: generate only multi fields that can store pointers to this type - `none`: do not generate fields that can store pointers to this type ''childFields'' (enum):: Similar to ''pointerfieldtypes'', but for fields that maintain a child/parent link ''parentFields'' (enum):: Similar to ''pointerfieldtypes'', but for the parent part of a child/parent link ''isNodeCore'' (bool):: Whether this type is (indirectly) derived from !NodeCore ''useLocalIncludes'' (bool):: Whether to use `#include "Foo.h"` instead of `#include ` ''additionalIncludes'' (string):: Additional header to include ''docGroupBase'' (string):: ''realparent'' (string):: === tag === ''name'' (string):: Name of the field ''category'' (enum):: - `data` The field stores some data (in contrast to a pointer). - `pointer` The field stores a pointer to another container. - `childpointer` The field stores a pointer to another container and maintains a parent pointer back to this container with the target. - `parentpointer` This field stores a parent pointer to another container, these fields are always managed by the corresponding `childpointer` field(s) - `weakpointer` This field stores a weak pointer to another container. ''linkParentField'' (string):: Only for category `childpointer`: the name of the parent field in the target type to use for child/parent linking. ''type'' (string):: Type of the value stored in this field. For any of the four pointer categories this should by just the name of the pointed to type, e.g. to get a field that stores a pointer to a Node, set `category="pointer"` `type="Node"`. ''typeNamespace'' (string):: ''cardinality'' (enum):: - `single` This field only stores a single value - `multi` This field stores many values (i.e. it behaves similar to std::vector) ''visibility'' (enum):: - `external` Field is externally visibile, it is transmitted in a cluster and stored in .osb files - `internal` The field is for internal data (e.g. that can be recomputed from other fields) and is not transmitted in a cluster or stored in .osb files ''fieldFlags'' (string):: ''defaultValue'' (string):: Default value this field is set to in the constructor (only for single fields) ''access'' (enum):: - `public` Accessor functions for the field are public - `protected` Accessor functions for the field are protected There is no `private` value, because fields are always members of the Base classes, so there is no meaningful way to access them if they are private ''defaultHeader'' (string):: Header file that contains the default value (normally this is not needed) ''fieldHeader'' (string, special):: Header file that defines the field type (e.g. MFFoo) for this field. If set to the special value "(AUTO)" (the default) it is deduced from the type (this works for types that are part of OpenSG). ''typeHeader'' (string, special):: Header file that defines the type stored in this field (e.g. Foo). If set to the special value "(AUTO)" (the default) it is deduced from the type (this works for types that are part of OpenSG). ''linkSParent'' (bool):: ''linkMParent'' (bool):: ''removeTo'' (string):: Value to store into mfields that have their remove function called ''pod'' (bool, special):: Whether the type is a POD (plain old datatype), or the special value "auto" to have it determined automatically (works for the OpenSG primitive types, e.g. UInt32, Real64, etc.) ''clearMField'' (bool):: Whether mfields are cleared in the destructor. ''ptrFieldAccess'' (enum):: - `std` - `nullCheck` - `custom` ''pushToFieldAs'' (string):: Name of the function to add values to an MField ''assignMFieldAs'' (string):: Name of the function to assign values from another MField ''insertIntoMFieldAs'' (string):: Name of the function to insert a value into an MField ''replaceInMFieldIndexAs'' (string):: Name of the function to replace a value (given by index) in an MField ''replaceInMFieldObjectAs'' (string):: Name of the function to replace a value (given by an object) in an MField ''removeFromMFieldIndexAs'' (string):: Name of the function to remove a value (given by index) from an MField ''removeFromMFieldObjectAs'' (string):: Name of the function to remove a value (given by an object) from an MField ''clearFieldAs'' (string):: Name of the function to clear an MField ----- || [wiki:Tutorial/OpenSG2/Memleak << Previous Chapter: Find Memory leaks] || [wiki:Tutorial Tutorial Overview] || [wiki:Tutorial/OpenSG2/NewContainerType Next Chapter: Creating new container types >>] ||