The s3eVideo API works in a similar manner to the s3eAudio API. To start playing a video clip we use the s3eVideoPlay function, specifying the filename of the video clip, the number of times we want it to loop, a screen position, and the size that we want to display it at, as follows:

s3eVideoPlay(lFileName, lRepeatCount, lX, lY, lWidth, lHeight);

The video clip will automatically resize to fit the rectangle, but no attempt is made to keep the correct aspect ratio.

Where possible it is usually best to try to make your video clips the same resolution as the rectangular area you want to display them in. This will avoid any unnecessary stretching of the image (which can look quite ugly!) and may lead to slightly better performance, though on most modern devices the resize will be happening in hardware and there will be no appreciable difference.

The actual size of the video file itself is also worth bearing in mind, since we often want to minimize the size of the final install package. Ultimately, we need to use a bit of trial and error until we get a result that ticks all the boxes for acceptable quality, performance, and file size.

The s3eVideo API makes use of the device's built-in video decoding, so not all video formats will be playable on all devices. To determine whether support for a particular codec is available, there is a function called s3eVideoIsCodecSupported that takes a value from the s3eVideoCodec enum. Take a look at the s3eVideo.h file or the Marmalade documentation for a complete list of possible values.

Again the parallels with the s3eAudio API are apparent when it comes to controlling video playback. The functions s3eVideoPause, s3eVideoResume, and s3eVideoStop all take no parameters and are used to pause, resume, and finish video clip playback respectively.

We have the choice of polling or callbacks once more for detecting the end of video playback. Let's start with the polled method that involves a call to the function s3eVideoIsPlaying, which will return S3E_TRUE if a video is playing or S3E_FALSE if a video is paused or stopped. Quite simple really!

If we want to use the callback approach, the following code snippet illustrates what to do:

int32 VideoFinished(void* apSystemData, void* apUserData)
{
  // apSystemData will always be NULL as there is no data associated
  // with this callback.
  // Return value is unimportant.
  return 0;
}

// To set up the callback function
s3eVideoRegister(S3E_VIDEO_STOP, (s3eCallback) VideoFinished, NULL);

// And to cancel it again...
s3eVideoUnRegister(S3E_VIDEO_STOP, (s3eCallback) VideoFinished);

The callback will be triggered whenever video playback stops, either because we explicitly call s3eVideoStop, an error in playback such as a corrupted video file occurs, or if an audio track is started using s3eAudioPlay. Note that the callback is not triggered between repetitions of the video clip if we are looping it.

For most games, video clips will probably only be used during introductory sequences or tutorials, since using video in the game itself is probably not practical. With this in mind, a polled approach for detecting when a video clip is finished is normally sufficient.

The s3eVideo API, like the s3eSound and s3eAudio APIs, also has a pair of functions for reading and writing global video parameters. They are called s3eVideoGetInt and s3eVideoSetInt. They are called as follows:

int32 lValue = s3eVideoGetInt(lProperty);
s3eVideoSetInt(lProperty, lValue);

The following table shows the values that can be used for the lProperty parameter: