Class TVRMLGLAnimation

DescriptionHierarchyFieldsMethodsProperties

Unit

VRMLGLAnimation

Declaration

type TVRMLGLAnimation = class(TVRMLAnimation)

Description

This is an animation of VRML model done by interpolating between any number of model states.

After constructing an object of this class, you must actually load it's animation by calling Load or LoadFromFile.

When loading you must provide one or more VRML models that have exactly the same structure, but possibly different values for various fields. Each scene has an associated position in Time (Time is just a float number). Scenes must be specified in increasing Time order. For example, first object may be a small sphere with blue color, the other object may be a larger sphere with white color, and the simplest times are 0.0 for the 1st scene and 1.0 for the 2nd scene.

This creates a list of Scenes such that

In effect, the Scenes is a list of scenes that, when rendered, will display an animation of the 1st object smoothly changing (morphing) into the 2nd object, then to the 3rd and so on, until the last object. In our example, the blue sphere will grow larger and larger and will fade into the white color. Of course, any kind of models is allowed — e.g. it can be a walking man at various stages, so in effect you get an animation of walking man.

A special case when you pass only one scene to this class is allowed (it may be handy in some situations). This will obviously produce just a still result, i.e. resulting TVRMLGLAnimation will be just a wrapper around single TVRMLFlatSceneGL instance.

All given objects must be "structurally equal" — the same nodes hierarchy, the same names of nodes, the same values of all fields (with the exception of fields that are interpolated: SFColor, SFFloat, SFMatrix, SFRotation, SFVec2f, SFVec3f and equivalent MFXxx fields). For multi-fields (MFXxx) that can be interpolated: note that values of items may differ, but still the counts of items must be equal.

Note that this is not the perfect way to design animations — a much better way would be to write the animation details in VRML file, use a modeller that allows you to design animations and store them in such way in VRML file, and read animations from this VRML file. But this means that many things must be done that currently are not ready — VRML 2.0 (and X3D) support must be done (they allow to write data about how model should be animated), and Blender exporter to VRML must store Blender animation data in VRML.

Until the things mentioned above are done, this class allows you to create animations by simply making two or more VRML scenes with various state of the same model. In many cases this should be acceptable solution.

Hierarchy

Overview

Methods

Public constructor Create(ACache: TVRMLOpenGLRendererContextCache = nil);
Public destructor Destroy; override;
Public procedure Load( RootNodes: TVRMLNodesList; AOwnsFirstRootNode: boolean; ATimes: TDynSingleArray; ScenesPerTime: Cardinal; AOptimization: TGLRendererOptimization; const EqualityEpsilon: Single);
Public procedure LoadStatic( RootNode: TVRMLNode; AOwnsRootNode: boolean; AOptimization: TGLRendererOptimization);
Public procedure LoadFromFile(const FileName: string; ChangeLoadParameters: TAnimationChangeLoadParametersFunc = nil);
Public procedure Close;
Public function ScenesCount: Integer;
Public function FirstScene: TVRMLFlatSceneGL;
Public function LastScene: TVRMLFlatSceneGL;
Public procedure PrepareRender( TransparentGroups: TTransparentGroups; Options: TPrepareRenderOptions; ProgressStep: boolean);
Public procedure FreeResources(Resources: TVRMLSceneFreeResources);
Public procedure CloseGL;
Public function TimeDuration: Single;
Public function TimeDurationWithBack: Single;
Public function SceneFromTime(const Time: Single): TVRMLFlatSceneGL;
Public function Attributes: TVRMLSceneRenderingAttributes;
Public function ManifoldEdges: TDynManifoldEdgeArray;
Public function BorderEdges: TDynBorderEdgeArray;
Public procedure ShareManifoldAndBorderEdges( ManifoldShared: TDynManifoldEdgeArray; BorderShared: TDynBorderEdgeArray);
Public function BoundingBoxSum: TBox3d;
Public procedure ChangedAll;
Public function Info(InfoTriVertCounts: boolean): string;
Public procedure WritelnInfoNodes;

Properties

Public property Loaded: boolean read FLoaded;
Public property OwnsFirstRootNode: boolean read FOwnsFirstRootNode;
Public property Scenes[I: Integer]: TVRMLFlatSceneGL read GetScenes;
Public property TimeBegin: Single read FTimeBegin;
Public property TimeEnd: Single read FTimeEnd;
Public property TimeLoop: boolean read FTimeLoop write FTimeLoop default true;
Public property TimeBackwards: boolean read FTimeBackwards write FTimeBackwards default false;
Public property BackgroundSkySphereRadius: Single read GetBackgroundSkySphereRadius write SetBackgroundSkySphereRadius;

Description

Methods

Public constructor Create(ACache: TVRMLOpenGLRendererContextCache = nil);

Constructor.

Public destructor Destroy; override;
 
Public procedure Load( RootNodes: TVRMLNodesList; AOwnsFirstRootNode: boolean; ATimes: TDynSingleArray; ScenesPerTime: Cardinal; AOptimization: TGLRendererOptimization; const EqualityEpsilon: Single);

This actually loads the animation scenes. You must call this (or some other loading routine like LoadFromFile) before you do almost anything with this object. Loaded changes to True after calling this.

Parameters
RootNodes
Models describing the "predefined" frames of animation.

For all nodes except the first: They are always owned by this class — that's needed, because actually we may do some operations on these models when building animation (including even freeing some RootNodes, if we will find that they are equivalent to some other RootNodes). They all must point to different objects.

You must supply at least one item here (you cannot make an animation from 0 items).

Times
Array specifying the point of time for each "predefined" frame. Length of this array must equal to length of RootNodes array.
ScenesPerTime
This says how many scenes will be used for period of time equal to 1.0. This will determine Scenes.Count. RootNodes[0] always takes Scenes[0] and RootNodes[High(RootNodes)] always takes Scenes[Scenes.High].

Note that if we will find that some nodes along the way are exactly equal, we may drop scenes count between — because if they are both equal, we can simply render the same scene for some period of time.

AOptimization
This is passed to TVRMLFlatSceneGL constructor, see there for docs.

Note that this class should generally use roSeparateShapeStatesNoTransform or roSeparateShapeStates for Optimization, to conserve memory in some common cases. See docs at TGLRendererOptimization type.

EqualityEpsilon
This will be used for comparing fields, to decide if two fields (and, consequently, nodes) are equal. It will be simply passed to TVRMLField.Equals.

You can pass here 0 to use exact comparison, but it's adviced to use here something > 0. Otherwise we could waste display list memory (and loading time) for many frames of the same node that are in fact equal.

Exceptions raised
EModelsStructureDifferent
When models in RootNode1 and RootNode2 are not structurally equal (see TVRMLGLAnimation comments for the precise meaning of "structurally equal" models).
Public procedure LoadStatic( RootNode: TVRMLNode; AOwnsRootNode: boolean; AOptimization: TGLRendererOptimization);

Load a dumb animation that consists of only one frame (so actually there's no animation, everything is static).

This just calls Load with parameters such that

  1. RootNodes list contains one specified node

  2. Times contain only one item 0.0

  3. ScenesPerTime and EqualityEpsilon have some unimportant values — they are not meaningfull when you have only one scene

This is usefull when you know that you have a static scene, but still you want to treat it as TVRMLGLAnimation.

Public procedure LoadFromFile(const FileName: string; ChangeLoadParameters: TAnimationChangeLoadParametersFunc = nil);

This loads TVRMLGLAnimation by loading it's parameters (models to use, times to use etc.) from given file. File format is described on [http://vrmlengine.sourceforge.net/kanim_format.php].

You can change some of the loaded parameters by providing ChangeLoadParameters callback (you can provide Nil, if you don't want to change them). ChangeLoadParameters callback is the only way to change some animation rendering parameters, like ScenesPerTime and AOptimization — after LoadFromFile finished, animation is fully loaded and these parameters cannot be changed anymore.

If you need more control than simple ChangeLoadParameters callback, you should use something more flexible (and less comfortable to use) like LoadFromFileToVars class procedure.

Note that you can always change TimeLoop and TimeBackwards — since these properties are writeable at any time.

Loaded property changes to True after calling this.

Public procedure Close;

This releases all resources allocared by Load (or LoadFromFile). Loaded property changes to False after calling this.

It's safe to call this even if Loaded is already False — then this will do nothing.

Public function ScenesCount: Integer;
 
Public function FirstScene: TVRMLFlatSceneGL;

Just a shortcut for Scenes[0].

Public function LastScene: TVRMLFlatSceneGL;

Just a shortcut for Scenes[ScenesCount - 1].

Public procedure PrepareRender( TransparentGroups: TTransparentGroups; Options: TPrepareRenderOptions; ProgressStep: boolean);

Prepare all scenes for rendering. This just calls PrepareRender(...) for all Scenes.

If ProgressStep then it will additionally call Progress.Step after preparing each scene (it will call it ScenesCount times).

If prManifoldAndBorderEdges is included, then actually a special memory (and prepare time) optimization will be used: only the first scene will have actually prepared prManifoldAndBorderEdges. The other scenes will just share the same ManifoldEdges and BorderEdges instances, by TVRMLFlatScene.ShareManifoldAndBorderEdges method.

Public procedure FreeResources(Resources: TVRMLSceneFreeResources);

This calls FreeResources for all scenes, it's useful if you know that you will not need some allocated resources anymore and you want to conserve memory use.

See TVRMLSceneFreeResource documentation for a description of what are possible resources to free.

Note in case you pass frRootNode: the first scene has OwnsRootNode set to what you passed as OwnsFirstRootNode. Which means that if you passed OwnsFirstRootNode = True, then frRootNode will not free the initial RootNodes[0].

Public procedure CloseGL;

Close anything associated with current OpenGL context in this class. This calls CloseGL on every Scenes[], and additionally may close some other internal things here.

Public function TimeDuration: Single;

Just a shortcut for TimeEnd - TimeBegin.

Public function TimeDurationWithBack: Single;

This is TimeDuration * 2 if TimeBackwards, otherwise it's just TimeDuration. In other words, this is the time of the one "full" (forward + backward) animation.

Public function SceneFromTime(const Time: Single): TVRMLFlatSceneGL;

This will return appropriate scene from Scenes based on given Time. If Time is between given TimeBegin and TimeEnd, then this will be appropriate scene in the middle.

For Time outside the range TimeBegin .. TimeEnd behavior depends on TimeLoop and TimeBackwards properties:

Public function Attributes: TVRMLSceneRenderingAttributes;

Attributes controlling rendering. See TVRMLSceneRenderingAttributes and TVRMLRenderingAttributes for documentation of properties.

You can change properties of this object at any time, but beware that some changes may force time-consuming regeneration of some things (like OpenGL display lists) in the nearest Render of the scenes. So explicitly calling PrepareRender may be useful after changing these Attributes.

Note that Attributes may be accessed and even changed when the scene is not loaded (e.g. before calling Load / LoadFromFile). Also, Attributes are preserved between various animations loaded.

Public function ManifoldEdges: TDynManifoldEdgeArray;

This simply returns FirstScene.ManifoldEdges. Since all scenes in the animation must have exactly the same structure, we know that this ManifoldEdges is actually good for all scenes within this animation.

Public function BorderEdges: TDynBorderEdgeArray;

This simply returns FirstScene.BorderEdges. Like ManifoldEdges: all scenes in the animation must have exactly the same structure, we know that this BorderEdges is actually good for all scenes within this animation.

Public procedure ShareManifoldAndBorderEdges( ManifoldShared: TDynManifoldEdgeArray; BorderShared: TDynBorderEdgeArray);

Calls ShareManifoldAndBoderEdges on all scenes within this animation. This is useful if you already have ManifoldEdges and BorderEdges, and you somehow know that it's good also for this scene.

Public function BoundingBoxSum: TBox3d;

The sum of bounding boxes of all animation frames.

Result of this function is cached, which means that it usually returns very fast. But you have to call ChangedAll when you changed something inside Scenes[] using some direct Scenes[].RootNode operations, to force recalculation of this box.

Public procedure ChangedAll;

Call this when you changed something inside Scenes[] using some direct Scenes[].RootNode operations. This calls TVRMLFlatSceneGL.ChangedAll on all Scenes[] and invalidates some cached things inside this class.

Public function Info(InfoTriVertCounts: boolean): string;

Returns some textual info about this animation. Similar to TVRMLFlatSceneGL.Info.

Public procedure WritelnInfoNodes;

Write contents of all VRML "Info" nodes. Also write how many Info nodes there are in the scene.

Actually, this just calls WritelnInfoNodes on the FirstScene — thanks to the knowledge that all info nodes in all scenes must be equal, since strings cannot be interpolated.

Properties

Public property Loaded: boolean read FLoaded;
 
Public property OwnsFirstRootNode: boolean read FOwnsFirstRootNode;
 
Public property Scenes[I: Integer]: TVRMLFlatSceneGL read GetScenes;

You can read anything from Scenes below. But you cannot set some things: don't set their scenes Attributes properties. Use only our Attributes.

Public property TimeBegin: Single read FTimeBegin;

First and last time that you passed to Load (or that were read from file by LoadFromFile). In other words, Times[0] and Times[High(Times)].

Public property TimeEnd: Single read FTimeEnd;
 
Public property TimeLoop: boolean read FTimeLoop write FTimeLoop default true;

See SceneFromTime for description what this property does.

Public property TimeBackwards: boolean read FTimeBackwards write FTimeBackwards default false;

See SceneFromTime for description what this property does.

Public property BackgroundSkySphereRadius: Single read GetBackgroundSkySphereRadius write SetBackgroundSkySphereRadius;

Common BackgroundSkySphereRadius of all scenes, see TVRMLFlatSceneGL.BackgroundSkySphereRadius.

This reads simply FirstScene.BackgroundSkySphereRadius and sets BackgroundSkySphereRadius for all scenes. So when reading this, it only makes sense if you always set all BackgroundSkySphereRadius to all (e.g. you set only by this property).

Note that there is doesn't really exist a requirement that all animation frames have the same BackgroundSkySphereRadius... But it's most common. In fact, it all depends on your needs, see TVRMLFlatSceneGL.BackgroundSkySphereRadius used by TVRMLFlatSceneGL.Background.

Generated by PasDoc 0.10.0 on 2008-02-25 00:00:41