SoField.h

/*=======================================================================
 * Copyright 1991-1996, Silicon Graphics, Inc.
 * ALL RIGHTS RESERVED
 *
 * UNPUBLISHED -- Rights reserved under the copyright laws of the United
 * States.   Use of a copyright notice is precautionary only and does not
 * imply publication or disclosure.
 *
 * U.S. GOVERNMENT RESTRICTED RIGHTS LEGEND:
 * Use, duplication or disclosure by the Government is subject to restrictions
 * as set forth in FAR 52.227.19(c)(2) or subparagraph (c)(1)(ii) of the Rights
 * in Technical Data and Computer Software clause at DFARS 252.227-7013 and/or
 * in similar or successor clauses in the FAR, or the DOD or NASA FAR
 * Supplement.  Contractor/manufacturer is Silicon Graphics, Inc.,
 * 2011 N. Shoreline Blvd. Mountain View, CA 94039-7311.
 *
 * THE CONTENT OF THIS WORK CONTAINS CONFIDENTIAL AND PROPRIETARY
 * INFORMATION OF SILICON GRAPHICS, INC. ANY DUPLICATION, MODIFICATION,
 * DISTRIBUTION, OR DISCLOSURE IN ANY FORM, IN WHOLE, OR IN PART, IS STRICTLY
 * PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF SILICON
 * GRAPHICS, INC.
**=======================================================================*/
/*=======================================================================
** Author      : Paul S. Strauss (MMM yyyy)
** Modified by : Nick Thompson (MMM yyyy)
** Modified by : Gavin Bell (MMM yyyy)
**=======================================================================*/
/*=======================================================================
 *** THE CONTENT OF THIS WORK IS PROPRIETARY TO FEI S.A.S, (FEI S.A.S.),            ***
 ***              AND IS DISTRIBUTED UNDER A LICENSE AGREEMENT.                     ***
 ***                                                                                ***
 ***  REPRODUCTION, DISCLOSURE,  OR USE,  IN WHOLE OR IN PART,  OTHER THAN AS       ***
 ***  SPECIFIED  IN THE LICENSE ARE  NOT TO BE  UNDERTAKEN  EXCEPT WITH PRIOR       ***
 ***  WRITTEN AUTHORIZATION OF FEI S.A.S.                                           ***
 ***                                                                                ***
 ***                        RESTRICTED RIGHTS LEGEND                                ***
 ***  USE, DUPLICATION, OR DISCLOSURE BY THE GOVERNMENT OF THE CONTENT OF THIS      ***
 ***  WORK OR RELATED DOCUMENTATION IS SUBJECT TO RESTRICTIONS AS SET FORTH IN      ***
 ***  SUBPARAGRAPH (C)(1) OF THE COMMERCIAL COMPUTER SOFTWARE RESTRICTED RIGHT      ***
 ***  CLAUSE  AT FAR 52.227-19  OR SUBPARAGRAPH  (C)(1)(II)  OF  THE RIGHTS IN      ***
 ***  TECHNICAL DATA AND COMPUTER SOFTWARE CLAUSE AT DFARS 52.227-7013.             ***
 ***                                                                                ***
 ***                   COPYRIGHT (C) 1996-2021 BY FEI S.A.S,                        ***
 ***                        BORDEAUX, FRANCE                                        ***
 ***                      ALL RIGHTS RESERVED                                       ***
**=======================================================================*/
/*=======================================================================
** Modified by : VSG (MMM YYYY)
**=======================================================================*/
 
 
#ifndef  _SO_FIELD_
#define  _SO_FIELD_
 
#include <Inventor/SbString.h>
#include <Inventor/SoTypedObject.h>
#include <Inventor/misc/SoNotification.h>
#include <Inventor/misc/SoAuditorList.h>
#include <Inventor/threads/SbThreadMutex.h>
#include <Inventor/threads/SbThreadLocalStorage.h>
#include <Inventor/sensors/SoDataSensor.h>
#include <Inventor/misc/SoMemoryObject.h>
 
class SoEngineOutput;
class SoVRMLInterpOutput;
struct SoFieldConnectionInfo;
class SoFieldContainer;
struct SoFieldAuditorInfo;
class SoFieldConverter;
class SoFieldList;
class SoInput;
class SoMemoryObject;
class SoNotList;
class SoOutput;
class SoFieldSensor;
 
#ifndef HIDDEN_FROM_DOC
// If the field is connected or there are any FieldSensors attached to
// this field, flags.hasAuditors will be TRUE, and this structure is
// used to contain the extra information needed.  Done this way to
// save space in the common case.
struct SoFieldAuditorInfo {
  SoFieldAuditorInfo()
  : container(NULL)
  { connection.field=NULL; }
 
  SoFieldContainer *container;
  
  // List of auditors: objects to pass notification to.
  SoAuditorList auditors;
  // The "connection" field points to either an engine output,
  // a VRMLInterpolator output, or
  // another field:
  union {
    SoEngineOutput *engineOutput;
    SoField *field;
    SoVRMLInterpOutput *interpOutput;
  } connection;
};
 
// If the field has a connections from other fields, there is a
// SoFieldConnectionInfo structure for each connection and the index
// of the last connection that touched this field is in the variable
// lastTouched. The variable numConnected containes the number of connections
// to this field. If multiple connections are allowed, this is also the
// next connection index.
struct SoFieldConnectionInfo {
  // The "connection" field points to either an engine output,
  // a VRMLInterpolator output, or
  // another field:
  void* indexToField;
  union {
    SoEngineOutput *engineOutput;
    SoField *field;
    SoVRMLInterpOutput *interpOutput;
  } connection;
  struct {
    unsigned int converted      : 1; // Connection required converter
    unsigned int fromEngine     : 1; // Connection is from engine
    unsigned int fromVRMLInterp : 1; // Connection is from
    // VRMLInterpolator
  } flags;
};
#endif // HIDDEN_FROM_DOC
 
//
//  Class: SoField
//
//  Base class for all kinds of fields.  SoField maintains the state
//  (ignored, modified, default, ...) of the field.
//
 
class  SoField: public SoTypedObject {
 
 public:
  
  // Destructor
#ifndef HIDDEN_FROM_DOC
  virtual ~SoField();
#endif // HIDDEN_FROM_DOC
  
  void setIgnored(SbBool ig);
  SbBool isIgnored() const      { return flags.ignored; }
 
  SbBool isDefault() const      { return flags.hasDefault; }
 
  static SoType getClassTypeId();
 
  void enableConnection(SbBool flag);
 
  SbBool isConnectionEnabled() const
    { return flags.connectionEnabled; }
 
  SbBool connectFrom(SoEngineOutput *engineOutput);
 
  SbBool connectFrom(SoField *field);
 
  SbBool connectFrom(SoVRMLInterpOutput *interpOutput);
 
  SbBool appendConnection(SoEngineOutput *engineOutput);
 
  SbBool appendConnection(SoField *field);
 
  SbBool appendConnection(SoVRMLInterpOutput *interpOutput);
 
  void disconnect(SoEngineOutput *engineOutput);
 
  void disconnect(SoField *field);
 
  void disconnect(SoVRMLInterpOutput *interpOutput);
 
  int getNumConnections() const
  {
    if (indexToConnectInfo)
      return indexToConnectInfo->getLength(); 
    return 0;
  }
 
  int getConnections(SoFieldList &list) ;
 
  void disconnect();
 
  SbBool isConnected() const { return flags.connected; }
 
  SbBool isConnectedFromVRMLInterp() const;
 
  SbBool isConnectedFromEngine() const;
 
  SbBool isConnectedFromField() const;
 
  // Returns the engine or field the output field is connected to.
  // Returns FALSE if there is no connection of the appropriate type.
 
  SbBool getConnectedEngine(SoEngineOutput *&engineOutput) const;
 
  SbBool getConnectedField(SoField *&writingField) const;
 
  SbBool getConnectedVRMLInterp(SoVRMLInterpOutput *&interpOutput) const;
 
  int getForwardConnections(SoFieldList &list) const;
 
  SoFieldContainer *getContainer() const;
 
  SoNONUNICODE SbBool set(const char *valueString);
 
  SbBool set( const SbString& valueString );
 
 
  void get(SbString &valueString);
 
  virtual size_t getValueSize() const { return 0; }
 
  virtual void touch();
 
  int operator ==(const SoField &f) const
  { return isSame(f); }
  int operator !=(const SoField &f) const
  { return ! isSame(f); }
 
 SoEXTENDER private:
  // Constuctor:
  SoField();
  
 private:
  static void initClass();
  static void exitClass();
 
  SB_THREAD_TLS_HEADER();
 
  // Initialize ALL Inventor node classes
  static void initClasses();
  static void exitClasses();
  
  // Sets value of field from the Inventor data file format
  // information in the value string.  Returns TRUE if successful,
  // FALSE otherwise. This is used in SoVRMLPROTOInstance to set the
  // fields value that is an SFNode. It is necessary for the SoInput created to 
  // know that this is a VRML2 file so it will know a PROTO if it it is the 
  // default field
  SbBool setVRML(const char *valueString);
  
  
  // Sets default flag
  void setDefault(SbBool def) { flags.hasDefault = def; }
  
  // Initiates or propagates notification through container
  virtual void startNotify();
  virtual void notify(SoNotList *list);
  
  // Sets the containing node.  This also calls enableNotify(TRUE)
  // and setDefault(TRUE).
  void setContainer(SoFieldContainer *cont);
  
  // Returns TRUE if the field really needs to be written out.
  // Fields with default values that aren't ignored and
  // aren't connected to anything will return FALSE.
  SbBool                shouldWrite() const;
  
  // Adds/removes an auditor to/from list
  void addAuditor(void *auditor, SoNotRec::Type type);
  void removeAuditor(void *auditor, SoNotRec::Type type);
  
  // Indicates whether notification will propagate as the result of
  // setting the field value. Engines turn this off when writing
  // results into fields, since notification has already propagated.
  SbBool enableNotify(SbBool flag);
  SbBool isNotifyEnabled() const
    { return flags.notifyEnabled; }
  
  // Indicates to a field that a change has been made involving a
  // connection from it (as source) to another field. Passed the
  // number of things being connected to the field; the number will
  // be negative when things are disconnected.
  // The default method does nothing.
  virtual void connectionStatusChanged(int numConnections);
  
  // If this returns TRUE, it means we're in the middle of doing a
  // setValue()+valueChanged() and values from an upstream
  // connection shouldn't write into this field.
  SbBool isReadOnly() const { return flags.readOnly; }
  
  // Returns TRUE if the given field is of the same type and has the
  // same value(s) as this. Subclasses must define this as well as
  // an == operator.
  virtual SbBool isSame(const SoField &f) const = 0;
  
  // Copies the value from one field to another, assuming same subclass
  virtual void copyFrom(const SoField &f) = 0;
  
  // After a field value has been copied using copyFrom(),
  // this is called to allow fields to update the copy. This is used
  // by node, engine, and path fields to make sure instances are
  // handled properly. The default implementation does nothing.
  virtual void fixCopy(SbBool copyConnections);
  
  // This returns TRUE if this field contains a reference to a node
  // or engine that is copied during a copy operation (i.e., it is
  // "inside"). The default method just checks if the field is
  // connected to such a node or engine. Subclasses may contain
  // other tests, such as those that contain pointers to nodes or
  // engines.
  virtual SbBool referencesCopy() const;
  
  // Copies connection from one field to another. Assumes fields are
  // the same subclass and that this field is connected.
  void copyConnection(const SoField *fromField);
  
  // Reads value of field (with given name) from file as defined by
  // SoInput. This does the work common to all fields, then calls
  // other read methods to do the rest.
  virtual SbBool read(SoInput *in, const SbName &name);
  
  // Writes field (with given name) to file as defined by SoOutput
  virtual void write(SoOutput *out, const SbName &name) const;
  
  // Counts write-references on field to prepare for writing
  virtual void countWriteRefs(SoOutput *out) const;
  
  // Evaluates the field from whatever it's connected to. If
  // there's no connection or we don't need to evaluate, this does
  // nothing. This has to be const because it's used by getValue
  // methods.
  void evaluate() const
    { if (flags.dirty) evaluateConnection(); }
  
  // This is used to set the fieldType member of the flags structure
  void setFieldType( int flagValue)
    { flags.fieldType = flagValue; };
  
  // This is used to get the fieldType member of the flags structure
  int getFieldType() const
    { return flags.fieldType; };
  
  // Get the dirty flag so that the actions know to evaluate the events
  SbBool getDirty() const
    { return flags.dirty; };
 
  void setDirty(SbBool value) 
    { flags.dirty = value; };
 
  // Get the userDataIsUsed flag
  SbBool getUserDataIsUsed() const
    { return flags.userDataIsUsed; };
 
  void setUserDataIsUsed(SbBool value)
    { flags.userDataIsUsed = value; };
 
  // Get the sameValueNotificationEnabled flag
  SbBool getSameValueNotificationEnabled() const
    { return flags.sameValueNotificationEnabled; };
 
  // Connects the field to the given output of an engine or to
  // another field. Returns FALSE if the connection could not be made.
  SbBool connectFrom(SoEngineOutput *engineOutput, SbBool notDefault);
  
  SbBool connectFrom(SoField *field, SbBool notDefault);
  
  // Connects the field to the given output of an VRMLInterpolator.
  // Returns FALSE if the connection could not be ade.
  SbBool connectFrom(SoVRMLInterpOutput *interpOutput, SbBool notDefault);
 
  // Connects the field to the given output of an engine or to
  // another field. Returns FALSE if the connection could not be made.
  SbBool connectFrom(SoEngineOutput *engineOutput,
                     SbBool notDefault, SbBool append);
  
  SbBool connectFrom(SoField *field, SbBool notDefault, SbBool append);
  
  // Connects the field to the given output of an VRMLInterpolator.
  // Returns FALSE if the connection could not be made.
  SbBool connectFrom(SoVRMLInterpOutput *interpOutput,
                     SbBool notDefault, SbBool append);
  
  // Changed to support FanIn for VRML2 but used by Inventor also.
  
  // Appends the field to the given output of an engine or to
  // another field. Returns FALSE if the connection could not be made.
  // An overloaded function to allow the appendConnection to not do
  // the notify if setting up a ROUTE-TO connection.
  SbBool appendConnection(SoEngineOutput *engineOutput,
                          SbBool notDefault);
  
  SbBool appendConnection(SoField *field, SbBool notDefault);
  
  // Connects the field to the given output of an VRMLInterpolator.
  // Returns FALSE if the connection could not be made.
  // An overloaded function to allow the appendConnection to not do
  // the notify if setting up a ROUTE-TO connection.
  SbBool appendConnection(SoVRMLInterpOutput *interpOutput,
                          SbBool notDefault);
 
  // Set callback function or lambda called on the field value change
  void setOnValueChangedCallback( const std::function<void( SoField* current )>& value );
 
  virtual bool isEnabledMemObj() { return false; }
  virtual SoMemoryObject* getMemObj() { return NULL; }
  virtual void setMemObj( SoMemoryObject* ) { }
 
 
  enum FieldType
  {
    HIDDEN_FIELD   = 0,
    EVENTIN_FIELD  = 1,
    EVENTOUT_FIELD = 2,
    FIELD_EVENTIN_FIELD = 3,
    INTERNAL_FIELD = 4,
    EXPOSED_FIELD  = 5,
    PRIVATE_FIELD  = 6,
    UNSUPPORTED_FIELD = 7
  };
 
 private:
  // Called by an instance to indicate that a value has changed. If
  // resetDefault is TRUE, this turns off default flag. Initiates
  // notification, if necessary.
  void valueChangedBasic(SbBool resetDefault = TRUE);
  
  // Evaluates the field or engine the field is connected to,
  // storing the result in the field. This is const because it is
  // called by evaluate().
  virtual void evaluateConnection() const;
  
  // Reads value(s) of field
  virtual SbBool readValue(SoInput *in) = 0;
  
  // Reads connection.
  virtual SbBool readConnection(SoInput *in);
  
  // Writes value(s) of field
  virtual void writeValue(SoOutput *out) const = 0;
  
  // Writes field connection
  virtual void writeConnection(SoOutput *out) const;
 
  // These are used by SoField::get()/SoMField::get1()
  // to hold the returned field string
  static SbThreadMutex s_classMutex;
  struct MTstruct
  {
    char *fieldBuf;
    size_t fieldBufSize;
  };
  // This is used to reallocate the string buffer used by SoField::get()
  static void *reallocFieldBuf(void *ptr, size_t newSize);
 
  // Number of values (0 by default for SoSField)
  // only used by SoMField but here for memory padding reasons.
  int num;
 
 private:
  static SoType classTypeId;
  // set if by default notification is triggered when doing SoSFField::setValue() with same value than previous.
  // this is controlled with OIV_ENABLE_SAMEVALUE_NOTIFICATION envvar. Default is TRUE.
  static bool s_defaultSameValueNotificationEnabled;
 
 
  // The "flags" field contains several bit flags:
  struct Flags {
    unsigned int hasDefault     : 1; // Field is set to default value
    unsigned int ignored : 1; // Field value is to be ignored
    unsigned int connected : 1; // Field connected from something
    unsigned int converted : 1; // Connection required converter
    unsigned int fromEngine : 1; // Connection is from engine
    unsigned int connectionEnabled : 1; // Connection is enabled
    unsigned int notifyEnabled : 1; // Notification is enabled
    unsigned int hasAuditors : 1; // Connected, or FieldSensor
    unsigned int isEngineModifying : 1; // Engine evaluating
    unsigned int readOnly : 1; // Must not write into this field
    unsigned int dirty : 1; // Field was notified and needs evaluation
    unsigned int fromVRMLInterp : 1; // Connection is from VRMLInterpolator
    unsigned int fieldType : 3; // Specifies field type for VRML2 nodes.
    unsigned int userDataIsUsed : 1; // 1 if user data array is used and if enableDeleteValues has never been called (only used by SoMField).
    unsigned int sameValueNotificationEnabled : 1; // 1 if doing a setValue() with same value than previous generate a notification (only used by SoSField)
    // 0 = hidden field         0 0 0
    // 1 = eventIn              0 0 1
    // 2 = eventOut             0 1 0
    // 3 = field and eventIn    0 1 1
    // 4 = internal field       0 0 1
    // 5 = exposedField         1 0 1
    // 6 = private field        1 1 0 // Useful for IvTune, fields which are not displayed
  };
  Flags flags;
 
  // If no other auditors, the container for this field is stored
  // directly here.  If the field has other auditors (flags.hasAuditors)
  // then the connection information and the container are
  // stored in an opaque SoFieldAuditorInfo structure.  This is
  // done to save space in the common case.
  union {
 
    SoFieldContainer *container;
 
    SoFieldAuditorInfo *auditorInfo;
  };
  
  SbPList *indexToConnectInfo;
  
  // Creates auditorInfo structure, if necessary:
  void createAuditorInfo();
  
  // Creates connectionInfo strucuture, if necessary:
  SoFieldConnectionInfo* createConnectionInfo(void* fromWhere);
 
  // return index of the connection info that have the indexToField member equal to fromWhere
  // -1 if not found
  int findConnectionInfo(void* fromWhere) const ;
  
  // Creates a converter engine to convert from the given field
  // type to the type of this field. Returns NULL on error.
  SoFieldConverter *createConverter(const SoType &fromFieldType) const;
  
  // Really disconnects field from whatever it's connected to
  void          reallyDisconnect();
  
  // Returns pointer to field converter, if fields was connected
  // through one
  SoFieldConverter *getConverter() const;
  
  // Looks up what field connection is from (container and field/output name)
  void getConnectionInfo(SoFieldContainer *&, SbName &) const;
 
  // Callback for field sync
  std::function<void( SoField* current )> m_onValueChanged;
  SoFieldSensor * m_onValueChangedFieldSensor;
 
  friend class SoEngineOutput;
  friend class SoVRMLInterpOutput;
};
 
// for compatibility we include also this 2 headers
// that were previously implemented here
#include <Inventor/fields/SoSField.h>
#include <Inventor/fields/SoMField.h>
 
#endif /* _SO_FIELD_ */