This file describes the nodegen utility.


NODEGEN:
=======

Converts a brief description of the node into a default C++ class
implementation.

input:
-----

The input node descriptions are very similar to the node descriptions
found in the VRML'97 specifications, for instance:

  Billboard [ Children Transforming ] {
    eventIn      MFNode   addChildren
    eventIn      MFNode   removeChildren
    exposedField SFVec3f  axisOfRotation 	0 1 0     # (-,)
    exposedField MFNode [ Children ] children   []
    field        SFVec3f  bboxCenter     	0 0 0     # (-,)
    field        SFVec3f  bboxSize       	-1 -1 -1  # (0,) or -1,-1,-1
  }

A node description consists of:

- node Id and optional parent node class specification between square brackets:
  . node name
  . parent node class Ids: referring to parent classes from which the
 	node will inherit state values and member functions. The description
	of the parent node classes preceeds the description of children
	node classes.

- between { ... }, a list of node interface members.
  All members need to be described, even if the member is inherited 
  from a parent class. The description of each member consists of:
  . kind: eventIn, field, exposedField, eventOut
  . type
    * for SFNode and MFNode fields and exposedFields, also the
	node class (e.g. [ Material ] for the material field of
	the Appearance node).
  . Id
  . for fields and exposedFields:
    * default field value
    * (in the future, also an optional value range will be specified here)

output:
------

Nodegen generates three files for each node class:

- a header file (e.g. Bilboard.H),
  containing declarations of node class member variables and functions.
  When adding utility member variables and functions to a node class
  (e.g. shader interface routines for a renderer), manual editing is
  possible in designated sections.

- a private C++ source file (e.g. BilboardP.C), containing all member
  functions that can be generated automatically from the input node
  description. This file does not need manual editing.

- a public C++ source file (e.g. Bilboard.C), containing declarations
  of member functions that cannot be implemented automaticalle, because
  they implement functionality that is specific for the node.

usage:
-----

Synopsis:

  nodegen catalog-file-name private|public|header|everything typeIds|all

Arguments:

. catalog-file-name: the file containing the input descriptions of the
  node classes to be generated and the parent node classes
. private|public|header|everything: indicates whether only the private
  source, public source, header file, or all three files need to be
  generated
. typeIds|all: list of the node type Ids to be generated. With 'all',
  code is generated for all nodes described in the catalog file.

The generated C++ files shall be copied to an appropriate directory, e.g.
XRML/nodes or XRML/PhBRML and added to the Makefile in this directory.
A default instance of the node class shall be added to the catalog
of builtin nodes in nodeCatalog.C in order to make the new node class
known to the parser.

notes:
-----

Catalog files with node descriptions can be found in the NODEGEN directory
(standard.nodes, phbrml.nodes).


Philippe Bekaert

January 19, 2001