Source/Base/Field/Field.dox

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