Full screen movies in iOS

Overview

Full screen movie playback is built in to iOS. We make use of this API to handle fullscreen movies (usually used to hide loading). Some platform independent information about fullscreen movies in UE3 can be found at FullScreenMovie. The iOS specific information (for instance, movie formats) you will need is found below.

In addition, you can use static images for loading instead of movies (or a combination thereof).

Content creation

This section will describe creation of movies and images, as well as naming considerations.

Movies

iOS supports multiple formats of movies, however at this time, we assume that all movies are M4V movies, with the .m4v extension.

The size of the movie can be pretty much anything (the playback zoom the movie up to fit the screen, while maintaining the aspect ratio of the movie, filling in the rest with black). A size of 480x320 (for landscape applications) or 320x480 (for portrait) is pretty standard, as that is the size of the smallest format screen. Zooming up on the iPad generally looks good.

Images

If the code can't play a movie (either because the movie doesn't exist, or it is running on OS version 3.1.3 or earlier), then it will attempt to find a .png file with the same name as the movie that was specified.

The image, like movies, can be any size, but generally sizes match the screen resolution you are targeting. It is actually possible to have 3 different images based on the same name, that will chosen from depending on the device the game is running on. Assuming the movie name is Loading, the three files you could specify are:

• IPadLoading.png - This would be chosen if the app is running on an iPad. Generally this would be 1024x768 (or 768x1024 for portrait apps)
• Loading@2x.png - This would be chosen if running on a device with a Retina Display (iPhone 4, iPod Touch 4th gen). Generally this would be 960x640 (or 640x960 for portrait apps)
• Loading.png - This would be used in any other case (or if the above files don't exist). Generally this would be 480x320 (or 320x480 for portrait apps)

Additionally, a small white spinner (UIActivityIndicatorView) is displayed in the lower left corner, to give some indication that the game is doing something (loading).

Specification

There are two methods of specifying a movie to play:: StartupMovies and LoadingMovies lines of the [FullScreenMovie] section of your engine .ini file, or by calling the various MoviePlayer functions in code (see FullScreenMovie for information about the functions, and the .ini / config settings). iOS movie playback is always streamed from flash memory, so the AlwaysLoadedMovies settings are ignored, as are the MM_* flags that specify where to play movies from. The only supported flag is whether or not the movie is looping.

Just like the final movie in the set of StartupMovies is a looping movie, if showing an image for the final "movie", that image will be shown until the game boots up. Note that the final movie/image won't even be shown if the game boots up before the 2nd to final movie finishes playing.

Important information about file case

The iOS API for loading movies/images is case-sensitive, so make sure that your movie names are specified (in the .ini or in code) with the exact case of the file on disk. In addition, the extension must be .m4v or .png (not .PNG for instance).

Special "Startup" movie

Because the OS will display Default.png before your app even loads, and then there is some time before the engine has read in the .ini files, the iOS movie player will always attempt to play a movie / image called Startup as soon as the engine starts up. If you don't have a movie called Startup, then there will be a pause and a black screen for a short period before your normal startup sequence begins.

Since we play movies early, specifying -nomovie on the commandline, or bForceNoMovies in your .ini file, does not have an effect on iOS.

Specifying image display times

Since images don't have any timing information included in them, there are .ini settings to control the length of time images are shown. You can control how long each image is shown, or a general time for all images, or leave it at the default of 4 seconds.

The time is determined in the following order (higher takes precedence):

• Looks in the [FullScreenMovie] section of the engine .ini for a key called SplashTime_XXX, where XXX is whatever the the image is called (minus extension).
• Looks in the [FullScreenMovie] section for a key called "DefaultSplashTime"
• 4 seconds

Input

If the engine is loaded and the movie is in the SkippableMovies list, clicking anywhere in the movie will stop the movie. If during the startup sequence, and there are more movies to play (not counting the final looping movie), the next movie will start.

Technical information

Unlike the Bink movie player, the iOS movie player runs in the main OS thread, not the rendering thread (nor the game thread). The main OS thread is the thread that all UIKit functionality runs (showing alerts, bringing up Game Center UI, etc). In general, the main thread is idle, so movies should start up very quickly.

Text overlays work (AddTextOverlay in script code) in iOS, but the game cannot render on top of the movie (with the Bink player, UE3 UFont objects are rendered on top of the movie using the Canvas). The iOS player will query the UFont specified for the max character height, multiply that by the specified YScale, and then use that number as the point size to create a iOS system font. CastleGame (as used in CastleMap - the Epic Citadel level) uses the newly added OnEngineLoaded script event to add a text overlay with "Start" so that users see that they are able to click in the movie to skip the remainder of the movie and start the game.