Cuepoints

This section explains the cuepoint feature.

What Are Cue Points?

A cuepoint allows timing information to be embedded into a movie.
The overall feature is called "cuepoint," while each piece of timing information is called an "event point."
To add cuepoints in a movie file, specify the cuepoint information file during encoding.

The following are some possible examples of using timing information.

• Vibrating the control pad in accordance with the movie scene.
• Moving polygon characters in accordance with the movie scene.
• Seeking the playback position in order to play a movie partway through. (See Specifying Seek Position by Cuepoints)

Retrieving Timing Information

You can retrieve event information embedded in a cuepoint in one of the following two ways.

(1) After header analysis, a list of all event points can be retrieved with the cuepoint information retrieval function.
(2) A callback function can be registered, which will be called every time the playback time reaches the time specified by the event point during playback.

Cuepoint Information

Cuepoint information can be retrieved with the criManaPlayer_GetCuePointInfo() function after the state of the CriManaPlayerHn handle becomes CRIMANAPLAYER_STATUS_WAIT_PREP.
Cuepoint information includes a list of all event points and the total number of event points in the movie.

Event Points

An event point is an individual timing information. A cuepoint consists of one or more event points.
Each event point contains the following parameters.

Event point information parameters

Parameter	Description
Name string	Used by the application to identify event points.
Time	Used by the library to call and determine the cuepoint callback function.
Type variable	An arbitrary integer value. Use when you want the application to easily distinguish between types of event points.
Parameter string	An arbitrary string. When you want to embed a special parameter, describe the parameter string and parse it with the application.

The character codes for the "name string" and "parameter string" are as per the cuepoint information file specified during encoding.

Cuepoint Callback

By registering a cuepoint callback function, you will call a callback function when the playback time reaches the event point during playback. The callback function argument is passed by the event point information.

The cuepoint callback function is registered by the criManaPlayer_SetCuePointCallback().
The cuepoint callback format is as follows.

• void(*) (void* obj, CriManaPlayerHn player, CriManaEventPoint *eventinfo);

Do not call the Sofdec2 library functions in the cuepoint callback functions.
If you need to control playback and get information with the callback, then just register the process as a callback function and call the actual Sofdec2 library function in the main thread.

When the Cuepoint Callback Function Is Called

The criMana_ExecuteMain() function decides whether to call the cuepoint callback function. (In the Sofdec2 framework, the application will call criMana_ExecuteMain() function every time through its main loop.)

When calling back through the main thread to match the parameters registered in the callback function, you can minimize the delay by determining the application callback after criMana_ExecuteMain().

Specifying Seek Position by Cuepoints

You can calculate the seek position (frame number) from the cuepoint information.
Use the time of the event point that you want to seek and call criManaPlayer_CalcFrameNoFromTime() function.
The criManaPlayer_CalcFrameNoFromTime() function is valid after header analysis.

There are also functions to specify a time and seek an event point around that time.
These functions can specify type variables for what is being sought. Specifying -1 in the type variable will let you seek all event points.

• criManaPlayer_SearchNextEventPointByTime()
• criManaPlayer_SearchPrevEventPointByTime()

Application: Chapter Skip Playback by Cuepoints

This section explains an application called chapter skip playback that uses a method of determining seek position from cuepoint information.

• Create the movie data
  Create a movie that has individual chapter positions as an event point.
  If you need to have other types of event points than chapter offsets, use type variables to distinguish between them. (For example, use type variable 0 for the chapter position and type variable 1 for timing information for other purposes.)
  
  
• Jump to the next chapter
  (1) Get the current playback time.
  (2) Search for the event point that comes after the current time with criManaPlayer_SearchNextEventPointByTime() and record the returned frame.
  (3) Stop movie playback.
  (4) Specify the frame number recorded in step (2) with criManaPlayer_SetSeekPosition().
  (5) Start movie playback.
  
  
• Return to the top of the current chapter / Return to the previous chapter
  (1) Get the current playback time and take one second off the time. Taking one second off the time will let you return to the previous chapter if the current playback position is within one second from the top of each chapter.
  (2) Specify the time calculated in (1) with criManaPlayer_SearchPrevEventPointByTime() and search for the event point. Record the returned frame number.
  (3) Stop movie playback.
  (4) Specify the frame number registered in step (2) with criManaPlayer_SetSeekPosition().
  (5) Start movie playback.
  

Cuepoint Restrictions

Cuepoints are only valid for simple playback and looped playback.
For sequential playback, the cuepoint will only be valid for the first movie playback.