Doc/to_port/Field.dox

   1 #include <OSGConfig.h>
   2
   3 using namespace OSG;
   4
   5 /*! \defgroup GrpBaseField Fields
   6     \ingroup GrpBase
   7
   8     See \ref PageBaseField for details.
   9 */
  10
  11 #if (OSG_DOC_LEVEL >= 3)
  12 /*! \defgroup GrpBaseFieldTraits Field Data Traits
  13     \ingroup GrpBaseField
  14
  15     ToDo
  16 */
  17 #endif
  18
  19 /*! \defgroup GrpBaseFieldSingle Single-Element Fields
  20     \ingroup GrpBaseField
  21
  22     ToDo
  23 */
  24
  25 /*! \defgroup GrpBaseFieldMulti Multi-Element Fields
  26     \ingroup GrpBaseField
  27
  28     ToDo
  29 */
  30
  31 /*! \defgroup GrpBaseFieldHelper Field Helper
  32     \ingroup GrpBaseFieldHelper
  33
  34     ToDo
  35 */
  36
  37 /*! \page PageBaseField Fields
  38
  39 All data in FieldContainers is organized in fields. There are two general
  40 types of fields, fields for single values (SFields) and fields for multiple
  41 values (MFields). For the standard types and most pointer and ptr types there
  42 are predefined instances of both types of fields.
  43
  44 \section SFields Single Fields
  45
  46 Single fields hold, as the name says, a single value. Their content can be
  47 accessed directly using getValue(); and setValue();. It can also be copied
  48 from another field of the same type by setValue(); (for fields of the same
  49 type) or by setAbstrValue(); (for fields which have the same type, but are
  50 given as an abstract field).
  51
  52 \section MFields Multi Fields
  53
  54 Multi fields hold multiple values. They are realized as STL vectors and offer
  55 a similar interface. The field defines types for iterators and references, and
  56 the standard begin(), end(), front(), back(), push_back(), insert(), erase(),
  57 clear(), size(), resize(), reserve() and other functions.
  58
  59 In addition, Multi fields have an interface reminiscent of single fields. It
  60 features the setValue() variants mentioned above and indexed variants like
  61 getValue(const UInt32 index) and setValue(const FieldTypeT &value, const
  62 UInt32 index) methods. It also features an OpenSG-style getSize() method.
  63
  64 \section  FCFields FieldContainer Fields
  65
  66 Each attribute has a name, e.g. someValue, and every field container has a set
  67 of standard access functions to access its fields. The field itself can be
  68 accessed via getSFSomeValue() or getMFSomeValue() for single or multiple value
  69 fields respectively.
  70
  71 For SFields containers features getSomeValue() and setSomeValue() direct
  72 access methods. The MField getSomeValue() method returns the whole field, just
  73 like the getMFSomeValue() method. Some field containers have more access
  74 functions, often something like an addSomeValue() method to simplify adding
  75 data to multi fields. See the field container docs for details.
  76
  77 */
  78
  79 #if !defined(OSG_DO_DOC) || OSG_DOC_LEVEL > 1
  80
  81 /*! \page PageBaseFieldExt Creating New Field Types
  82
  83 All the data that is kept in FieldConatiners has to be in Fields. Fields
  84 provide the interface for the reflecivity and generic access methods to work.
  85 They come in the two known variants single and multi field. To simplify
  86 creating new field types, they do not have to created explicitly. Instead
  87 there are templates SField and MField who take care of the implementation. All
  88 you need to provide is a Trait structure that defines the types needed and
  89 some type-specific functions.
  90
  91 Note that field types for new FieldContainers (actually pointers to
  92 FieldContainers, as you can't instantiate them) can be created by fcdEdit
  93 automatically. So if you need fields for pointers to your containers, you
  94 don't have to follow the descriptions in this section.
  95
  96 The trait has to be a concrete version (What's the right name for this?) of
  97 FieldDataTrait<class type> and has to provide the following functions/types:
  98
  99 \li a DataType _type; which is used to uniquely identify the Field's type
 100
 101 \li an access method for the type: DataType &getType(void)
 102
 103 \li two methods to return the names of the field types: Char8 *getSName(void)
 104 and Char8 *getMName(void). The names are usually created by capitalizing the
 105 type name and prepending SF or MF, e.g. the matrix field names are SFMatrix
 106 and MFMatrix.
 107
 108 \li a method to get a default object to initialize the values: type
 109 getDefault(void).
 110
 111 \li two methods to convert a data element to and from a string: Bool
 112 getFromString(type &outVal, const Char8 *&inVal); and void putToString(const
 113 type &inVal, string &outVal);. Note that these are optional in the sense that
 114 the system will work without them, but some important features will not work
 115 without them, so it's highly recommended to implement them.
 116
 117 \li In any case, if they are implemented or not, this has to be announced by
 118 adding an anonymous enum value for StringConvertable which can be a binary
 119 combination of ToStringConvertable and FromStringConvertable.
 120
 121 Note that all functions have to be static, as the Trait class is not
 122 instanced, and that the Trait cannot have any virtual functions or data
 123 memebrs. It is not used to create actual objects, it's just a convenience
 124 container for the needed types/functions.
 125
 126 The fields also need to be able to store themselves in a binary form. If the
 127 data structures used are contiguous in memory and don't use pointers this can
 128 easily be accomplished by deriving the FieldDataTrait<class type> from
 129 FieldTraitsRecurseBase<type>. It will copy the contents of the data types
 130 verbatim and back.
 131
 132 This approach will not work as soon as there are pointers in the new
 133 structures, even simple things like STL vectors will not work that way.
 134
 135 In these cases you need to implement the binary interface in the trait. It
 136 consists of three method, which exist for single and multiple elements of the
 137 type:
 138
 139 \li a method to calculate the size of the packed object: UInt32
 140 getBinSize(const type &object);
 141
 142 \li a method to put the object into a binary block: void
 143 copyToBin(BinaryDataHandler &mem, const type &object);
 144
 145 \li a method to receive the object from a binary memory block: void
 146 copyFromBin(BinaryDataHandler &mem, type &object);
 147
 148 The last two methods work via a BinaryDataHandler, which abstracts a memory
 149 block.
 150
 151 There are some details that have to be done in order for all the static
 152 elements to be available and all necessary templates to be instatiated.
 153 Especially for types that are to be used in libraries on Windows some
 154 constraints need to be satisfied.
 155
 156 For an example on how to implement new Field types, see Examples/NewTypes in
 157 the source code or source distribution.
 158
 159 */
 160
 161 #endif
 162
 163