Snapshot Association

It may not be desirable for the latest snapshot to always be the one displayed. For example, if the simulation and rendering of the application are decoupled, it is possible for two simulation steps to be taken before the corresponding rendering for each simulation occurs. The diagram below depicts such a situation.

Without the ability to associate Capture calls with NextCapture calls, both Render #1 and Render #2 steps renders the state of the GFx::Movie as it was when Capture #2 was taken. To support applications which require the exact state of the GFx::Movie at a particular time to be displayed, GFx::Movie::Capture returns a snapshot identifier, which can be passed to MovieDisplayHandle::NextCapture call. This will cause the Display call of the same handle to reflect the state of the GFx::Movie as it was when the snapshot identifier was generated. This is shown in the diagram below:

Now, Render #1 will render the state of Capture #1, and Render #2 will render the state of Capture #2, even though the Capture calls both completed before either Render step began.

There is a limitation with the snapshot association feature. You cannot reorder snapshot identifiers obtained from Capture into NextCapture calls. When a snapshot identifier is passed to NextCapture, all older snapshots are invalidated. If this is attempted, the request will be ignored, and the last frame will be rendered. For example, the following will cause the state of the Movie to be rendered twice for frameID1:

UInt64 frameID0 = Movie::Capture();
UInt64 frameID1 = Movie::Capture();
MovieDisplayHandle::NextCapture(pHAL, frameID1);
MovieDisplayHandle::NextCapture(pHAL, frameID0);

To use snapshot associations, an explicit call to GFx::Movie::Capture must be made, to obtain the snapshot ID. Also be aware that by default GFx::Movie::Advance calls Capture internally, unless the capture parameter is false (true by default). Calling Advance with capture=true, then immediately calling Capture is less efficient than passing capture=false.

The snapshot association feature was introduced in Scaleform 4.4.30, but is disabled by default. To enable it, you must modify GFxConfig.h and uncomment the line:

#define SF_RENDER_CONTEXT_V1

This will require recompilation of the Scaleform libraries, and thus, is only available to source licensed customers. If you attempt to use this feature (passing frameIDs to NextCapture) without rebuilding, you will get a warning message in debug.