intuitiv'3d API documentation Copyright ã1993 by Cub'x SystÜmes. All Rights Reserved.

Exported Variables

Exported Variables is a function package that has been designed to speed-up the realization of archiving methods and, for future use, to allow a class to simply export instance variable that are consistent. A class that needs to use exported variable has to provide a method ( - exportedVariable: , - exportedVariableFor:  ) that returns a data representation which  describes instance variable names and types. 
A function called inside the - read or - write method implementation of an abstract super-class then asks the caller  its exported variable and performs the read or write operations. 
A class only has to describe its own instance variable, not the instance variables inherited from its super-class. The Exported Variable package uses the Objective-C run-time functions to read the inheritance tree and asks each class that provides the exportation method for exported variable .

	Types and constants used to describe instance variables

	Variables types are described using the following constants:

		Constant:					Objective C / Renderman / Appkit Type
		EV_FLOAT					float
		EV_DOUBLE					double
		EV_CHAR					char
		EV_UCHAR					unsigned char
		EV_SHORT					short
		EV_LONG					long
		EV_INT					int
		EV_UINT					unsigned int
		EV_BOOL					BOOL
		EV_OBJECT					id
		EV_3DPOINT					float[3]
		EV_NXCOLOR					NXColor
		EV_NULL					specify the end of the exported variable array.

	The ExportedVariable type describes an instance variable:

	typedef struct _ExportedVariable
	{
  		char  		*variableName;            
		char 		*variableType;              
 		unsigned long 	  variableLength;    
	              } ExportedVariable;

		variableName				a constant string that contains the name of the instance variable.

		variableType				a EV_xxx constant according to the type of the variable or EV_NULL if this is the end of the exported variable array.

variableLength				contains the number of element inside your instance variable. If your variable is not an array, you can initialize this field with 0 or 1. Otherwise, you should initialize variableLength with the number of element in your array.

	Methods that should be implemented to describe instance variables.

If you want to export your own instance variable, you have to provide one of the following methods. If your subclass doesn't add any new instance variable, you don't have to do anything.

	exportedVariable
	+ (ExportedVariable*) exportedVariable
This method returns the instance variable description of the receiving class. A typical implementation is done using a static auto-initialized array of ExportedVariable:

+ (ExportedVariable*) exportedVariable
	{
	   static ExportedVariable ev[] = {
		{"MyVar1", EV_FLOAT, 1 },
		{"MyVar2",EV_BOOL,     1 },
		{NULL,EV_NULL, 0}};
	   return ev;
	}

	exportedVariableFor:
	+ (ExportedVariable*) exportedVariableFor: (long) classVersion
This method is the same than - exportedVariable but gives you a chance to return a different version of exported variable according to the class version. Exported Variable functions first attempts to call the + exportedVariable method and then attempts to call + exportedVariableFor: method.  Here is a typical implementation  of the + exportedVariableFor: method: 

+ (ExportedVariable*) exportedVariableFor:(long) classVersion
	{
	    switch( classVersion )
		{
	                    case 0:
			return ev_version_0;
	                     case 1:
			return ev_version_1;
			...
		}
	}

	Functions to use the Exported Variable package.

	Inside intuitiv'3d you rarely have to use theses functions directly since they are called in all abstract super-classes (CX3DObject / CX3DNode / CX3DShader ). Nevertheless, if you have to make new classes that don't inherit from an intuitiv'3d's abstract super-class, you are encouraged to use the Exported Variable package.

evReadVariableForObject

	SUMMARY	Read from an NXTypedStream the exported variable of an object.

	DECLARED IN	i3d/ExportedVariable.h

	SYNOPSIS

void evReadVariableForObject(NXTypedStream *s,id obj)

	DESCRIPTION	This function asks all classes of obj for the exported variables , reads from the streams variable's values and then initialize the instance obj. You can call this function inside the - read: implementation of your class. Here is a typical implementation of the - read: method:

		- read:(NXTypedStream*)s
		{
		  [super read:s];
		  evReadVariableForObject(s,self);
		  return self;
		}

evWriteVariableForObject

	SUMMARY	Write to an NXTypedStream the exported variable of an object.

	DECLARED IN	i3d/ExportedVariable.h

	SYNOPSIS

void evWriteVariableForObject(NXTypedStream *s,id obj)

	DESCRIPTION	This function ask all classes of obj for the exported variable and then writes to the stream s variable's values.  You can call this function inside the - write: implementation of your class. Here is a typical implementation of the - write: method:

		- write:(NXTypedStream*)s
		{
		  [super write:s];
		  evWriteVariableForObject(s,self);
		  return self;
		}

	Important note 
Although Exported Variable supported types includes most of the types used, there are cases where you cannot use exported variable for all instance variables. For example, exported variables do not support strings or complex data representations. In this case, you can export variables that are exportable and overload - read: and - write: methods in order to save un-exported variables.