20070301 04/25 20080225 0721 1123 1213 (75-2)

*View SAI Abstract Standard

The X3D Abstract standard, Part 2, describes the X3D Scene Access Interface (SAI) that provides 'internal' and 'external' program access to the X3D browser and to the current scene. Like 19975 Part 1, the interfaces are described in a form that is independent of the actual implementation language/platform. This is my quick reference for the abstract SAI.




TheFinalDetail = 
  SAIBrowserRef.SAIExecutionContext.SAINode.SAIField.SAIFieldValue;


X3D browser 'external' events default = 
* external event becomes internal event as received; 
  each with new internal timestamp, thus new cascade 
* external events buffered between beginUpdate/endUpdate become internal events; 
  all have same internal timestamp, thus same cascade  

X3D browser 'internal' events default = 
* initial output-capable field change event sets timestamp for resulting cascade 
* script output event(s) sent with initial timestamp when script completes
  beginUpdate when script starts; endUpdate when script complete
* script directOutput event(s) sent as set; 
  (separate from current cascade, directOutput does not initiate new cascade)


SAINode.SAIField.SAIFieldValue lifecycle
Field typeCreationSetupRealizedDisposed
initializeOnlyNonereadable/writableNoneNone
inputOnlyNoneNonewritableNone
outputOnlyNoneNonereadableNone
inputOutputNonereadable/writablereadable/writableNone
External Browser services createBrowser(SAIParameterList, SAIPropertyList); create X3D browser instance return new SAIBrowserApp getBrowser(SAIParameterList); return SAIBrowserRef updateControl(SAIBrowserRef, SAIAction); SAIAction = BeginUpdate|EndUpdate dispose(SAIBrowserRef); no further interest; X3D browser returns SAI_Browser_Shutdown event SAIBoolean = setBrowserOption(SAIBrowserRef, SAIString, SAIObject); set defined Browser options dispose(SAIExecutionContext); no further interest; X3D browser may reclaim resources consumed by this execution context. prepareEvents; called every frame; evaluate directOutput(s), evaluate cascade(s) eventsProcessed(SAIBrowserRef); current event cascade processing for this node is complete; please update scene graph shutdown; user code is no longer functional or executed Internal Browser services The main containing scene, each proto instance, and each inline instance is a distinct and independent execution context in the current scene graph. SAIBrowserName = getName(SAIBrowserRef); name of X3D browser SAIBrowserVersion = getVersion(SAIBrowserRef); version of X3D browser SAINavSpeed = getCurrentSpeed(SAIBrowserRef, SAILayerID); navigation speed SAIFrameRate = getCurrentFrameRate(SAIBrowserRef); current frame display rate SAIProfileDeclaration[s] = getSupportedProfiles(SAIBrowserRef); list of supported profiles SAIProfileDeclaration = getProfile(SAIBrowserRef, SAIString); declaration of named profile SAIComponentDeclaration[s] = getSupportedComponents(SAIBrowserRef); list of supported components SAIComponentDeclaration = getComponent(SAIBrowserRef, SAIComponent); declaration of the named component SAIExecutionContext = getExecutionContext(SAIBrowserRef); current execution context SAIScene = createScene(SAIBrowserRef, [SAIProfileDeclaration], [SAIComponentDeclaration]s); creates new empty scene replaceWorld(SAIBrowserRef, SAIScene); replace current scene with new scene SAIScene = importDocument(SAIBrowserRef, DOMNode); import W3C DOM string, return X3D syntax loadURL(SAIBrowserRef, SAIURL [SAIURL]s, SAIPropertyList); replace current scene with new X3D scene setDescription(SAIBrowserRef, SAIString); set new scene description title SAIScene = createX3DFromString(SAIBrowserRef, SAIString); process string, return X3D syntax SAIScene = createX3DFromStream(SAIBrowserRef, SAIStream); process stream, return X3D syntax SAIScene = createX3DFromURL(SAIBrowserRef, SAIURL [SAIURL]s); process url, return X3D syntax updateControl(SAIBrowserRef, SAIAction); SAIAction = BeginUpdate|EndUpdate registerBrowserInterest(SAIBrowserRef, SAIAction, SAIRequester); SAIAction = AddBrowserInterest|RemoveBrowserInterest SAIPropertyList = getRenderingProperties(SAIBrowserRef); String any|Flat|Gouraud|Phong|Wireframe = getShading(); String maximum texture size WIDTHxHEIGHT = getMaxTextureSize(); Integer multitexture texture units = getTextureUnits(); Boolean if anti-aliased = getAntiAliased(); Integer bits of screen colour depth = getColorDepth(); Float memory in megabytes = getTextureMemory(); SAIPropertyList = getBrowserProperties(SAIBrowserRef); Boolean if ABSTRACT_NODES Boolean if CONCRETE_NODES Boolean if EXTERNAL_INTERACTIONS Boolean if PROTOTYPE_CREATE Boolean if DOM_IMPORT Boolean if XML_ENCODING Boolean if CLASSIC_VRML_ENCODING Boolean if BINARY_ENCODING changeViewpoint(SAIBrowserRef, SAIAction, SAILayerID); select viewpoint SAIAction = Next|Previous|First|Last print(SAIBrowserRef, SAIString); print to X3D browser console dispose(SAIBrowserRef); exit browser; generate SAI_Browser_Shutdown event SAIBoolean = setBrowserOption(SAIBrowserRef, SAIString, SAIObject); set defined Browser options Execution context services SAIString = getSpecificationVersion(SAIExecutionContext); specification version string SAIEncoding = getEncoding(SAIExecutionContext); encoding string SAIEncoding = Scripted|ASCII|VRML|XML|Binary|BIFS SAIProfileDeclaration = getProfile(SAIExecutionContext); profile string SAIProfileDeclaration = from profile list SAIComponentDeclaration[s] = getComponents(SAIExecutionContext); components list SAIComponentDeclaration[s] = from components list SAIURL = getWorldURL(SAIExecutionContext); world url string SAINode = getNode(SAIExecutionContext, SAIString, SAIAction); return named node SAIAction = DEFNode|IMPORTNode|EXPORTNode SAINode = createNode(SAIExecutionContext, SAIString); create X3D node SAIString = name of an X3D node type SAINode = createProto(SAIExecutionContext, SAIString); create proto instance SAIString = name of PROTO namedNodeHandling(SAIExecutionContext, SAIAction, SAIAction, SAIString, [SAINode | SAIString, [SAIString]]); action named node SAIAction = AddDEFNode|UpdateDEFNode|RemoveDEFNode| AddIMPORTNode|UpdateIMPORTNode|RemoveIMPORTNode| AddEXPORTNode|UpdateEXPORTNode|RemoveEXPORTNode SAIProtoDeclaration = getProtoDeclaration(SAIExecutionContext, SAIString); return proto declaration SAIString = named PROTO declaration protoDeclarationHandling(SAIExecutionContext, SAIString, SAINode, SAIAction); action extern proto declareation SAIAction = AddProto|UpdateProto|RemoveProto SAIProtoDeclaration = getExternProtoDeclaration(SAIExecutionContext, SAIString); return extern proto declaration externprotoDeclarationHandling(SAIExecutionContext, SAIString, SAINode, SAIAction); action extern proto declareation SAIAction = AddExternProto|UpdateExternProto|RemoveExternProto SAINodes = getRootNodes(SAIExecutionContext); listing of current root nodes SAIRoutes = getRoutes(SAIExecutionContext); return route list dynamicRouteHandling(SAIExecutionContext, SAINode, SAIField, SAINode, SAIField, SAIAction); action route SAIAction = AddRoute|DeleteRoute dispose(SAIExecutionContext); no further interest in context Scene services SAIString = getMetadata(SAIScene, SAIString); return an item of metadata setMetadata(SAIScene, SAIString, SAIString); inserts an item of metadata namedNodeHandling(SAIExecutionContext, SAIAction, SAIAction, SAIString, [SAINode | SAIString, [SAIString]]); action named node SAIAction = AddDEFNode|UpdateDEFNode|RemoveDEFNode| AddIMPORTNode|UpdateIMPORTNode|RemoveIMPORTNode| AddEXPORTNode|UpdateEXPORTNode|RemoveEXPORTNode rootNodeHandling(SAIScene, SAINode, SAIAction); action named root node SAIAction = AddRootNode|RemoveRootNode If AddRootNode when the node or children is currently part of another scene, generate SAI_NODE_IN_USE Node services SAIString = getTypeName(SAINode); SAINodeType = getType(SAINode); SAIField = getField(SAINode, SAIFieldName); SAIFieldsgetFieldDefinitions(SAINodeType); dispose(SAINode); no further interest Field services SAIFieldAccess = getAccessType(SAINode, SAIField); SAIFieldType = getType(SAINode, SAIField); SAIFieldName = getName(SAINode, SAIField); SAIFieldValue = getValue(SAINode, SAIField); setValue(SAINode, SAIField, SAIFieldValue); registerFieldInterest(SAINode, SAIField, SAIAction, SAIRequester); action field interest SAIAction = AddInterest|RemoveINteres dispose(SAIField); no further interest Route services SAINode = getSourceNode(SAIRoute); SAIString = getSourceField(SAIRoute); SAINode = getDestinationNode(SAIRoute); SAIString = getDestinationField(SAIRoute); dispose(SAIRoute); Prototype services SAIBoolean = isExternproto(SAIProtoDeclaration); SAINode = createInstance(SAIProtoDeclaration); SAIField[s] = getFieldDefinitions(SAIProtoDeclaration); SAILoadState = checkLoadState(SAIProtoDeclaration); requestImmediateLoad(SAIProtoDeclaration); Configuration services SAIString = getComponentName(SAIComponentDeclaration); SAIString = getComponentLevel(SAIComponentDeclaration); SAIString = getProfileName(SAIProfileDeclaration); SAIComponentDeclaration[s] = getProfileComponents(SAIProfileDeclaration); SAIString = getProviderName(SAIProfileDeclaration) Script Services setBrowser(SAIBrowserRef); setFields(SAINode, SAIField, [SAIField]s ) initialize; the user code is active prepareEvents; called every frame; evaluate directOutput(s), evaluate cascade(s) eventsProcessed(SAIBrowserRef); current event cascade processing for this node is complete; please update scene graph shutdown; user code is longer functional or executed 3x3 and 4x4 Matrix services set(SAIMatrix, SFVec3f, SFRotation, SFVec3f, SFRotation, SFVec3f); for the matrix set translation, rotation, scale, scaleOrientation, center get(SAIMatrix, SFVec3f, SFRotation, SFVec3f); from the matrix return translation, rotation, scale inverse(SAIMatrix); inverse this matrix in place transpose(SAIMatrix); transpose this matrix in place multiply(SAIMatrix, SAIMatrix); multiply first matrix by second matrix place result first matrix multiplyWithVector(SAIMatrix, SFVec3f); both left and right Data type definitions SAIAction SAIBoolean SAIBrowserApp SAIBrowserName SAIBrowserRef SAIBrowserVersion SAIComponentDeclaration SAIComponent SAIEncoding SAIExecutionContext SAIFieldAccess SAIFieldDeclaration SAIField SAIFieldName SAIFieldType SAIFieldValue SAIFrameRate SAILayerID * SAILoadState SAIMatrix * SAINavSpeed SAINode SAINodeType SAIParameterLIst SAIProfileDeclaration SAIPropertyList SAIProtoDeclaration SAIRequester SAIRoute SAIScene SAIScript SAIScriptImplementation SAIStream SAIString SAIURL NULL Error types SAIError SAI_BROWSER_UNAVAILABLE SAI_CONNECTION_ERROR SAI_DISPOSED SAI_IMPORTED_NODE SAI_INSUFFICIENT_CAPABILITIES SAI_INVALID_ACCESS_TYPE SAI_INVALID_BROWSER SAI_IINVALID_DOCUMENT SAI_INVALID_EXECUTION_CONTEXT SAI_INVALID_FIELD SAI_INVALID_NAME SAI_INVALID_NODE SAI_INVALID_OPERATION_TIMING SAI_INVALID_URL SAI_INVALID_X3D SAI_NODE_IN_USE SAI_NODE_NOT_AVAILABLE SAI_NOT_SHARED SAI_NOT_SUPPORTED SAI_URL_UNAVAILABLE Event types SAI_Browser_Event SAI_Browser_Initialized SAI_Browser_Shutdown SAI_Browser_Connection_Error SAI_Browser_URL_Error SAIFieldEvent