Context Navigation

Chapter Overview

fcd2code - OpenSG 2 code generator

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 Description below) for the container.

-f, --write-fc

Writes the User files (see 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 <prefix>/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: <FieldContainer> and <Field> and there may only be one <FieldContainer> tag per file and all <Field> tags must be inside it. All important information is stored in attributes of these tags (see below).

<?xml version="1.0" ?>

<!FieldContainer>
        Description of the container

        <Field>
        Description of the first field. 
        </Field>

        <Field>
        Description of the second field.
        </Field>
</FieldContainer>

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

<FieldContainer> 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 <Foo.h>

additionalIncludes (string): Additional header to include

docGroupBase (string)

realparent (string)

<Field> 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

<< Previous Chapter: Find Memory leaks

Tutorial Overview

Next Chapter: Creating new container types >>

Download in other formats:

Plain Text

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