The background plane is the bottom-most plane, located below the video. You can change the color of this plane using setBackgroundColor, or display an image on it using setBackgroundImage.
To use background images, you first have to add them to the project. In the main menu select Project → "Background images" and add the required images (*.jpg files).
Please note that this feature requires JAR signing.
Once a background image has been added, you can use the setBackgroundImage function to display it. The image names are bg[X].[extension], where [X] is the index in the list, starting from 1. Thus, the first image in the list is bg1.jpg (if the first file has the extension .jpg) and the function call is:
manager.setBackgroundImage("bg1.jpg");
In the "Project properties" → "Parameters & Functions" → "Scripts" → "Image loaded" you can specify a script that is executed when an image has been loaded.
We recommend using images smaller than 1 MB. Images larger than 3.5 MB may not work on some players.
Hardware players support only baseline JPEG images - a progressive JPEG may look fine in PowerDVD, but a real player will not show it at all. During the compilation the application checks every background image and automatically re-encodes the incompatible ones (progressive encoding, size above 1920x1080 and so on), adding a warning to the Log window. Only the copy placed on the disc is converted - the original file is not modified, but it is still recommended to re-save the original as a baseline JPEG to avoid the extra re-encoding on every compilation.
setBackgroundImage reads the image from the disc at the moment you call it, so the image appears with a delay - on a slow player a large picture may take a noticeable time to show up. If you know in advance which images will be needed, load them into the memory beforehand and show them later without any delay:
manager.preloadBackgroundImage("bg1.jpg");
manager.preloadBackgroundImage("bg2.jpg");
Loading is performed in the background, so these calls return immediately and the menu stays responsive. The "Image loaded" script is executed each time one of the images finishes loading. A good place for preloading is the very beginning of the disc (the loading stage) or the Enter action of the menu preceding the one where the image is needed.
If you want all the images to be ready from the very beginning, you do not have to write these calls at all - enable "Project properties" → "Menu" → "Preload all background images on disc load" and the application adds a preloadBackgroundImage call for every image in the list while the disc is loading. This is the simplest approach when the project has only a few small images. If the project has many images, or large ones, preload them manually instead - see "Releasing the memory" below.
Whichever way you preload the images, remember that the "Image loaded" script is executed once per image, and not only when a background image appears on the screen. Preloading five images calls it five times. The script gets two predefined variables - boolean isFailed and String fileName - so it can tell which image it was called for and whether the loading succeeded:
if (isFailed) {
manager.showLog("cannot load " + fileName);
} else if (fileName.equals("bg1.jpg")) {
manager.showBackgroundImage("bg1.jpg");
}
When the image is required, show it:
manager.showBackgroundImage("bg1.jpg");
If the image was preloaded, it appears instantly. If it was not, showBackgroundImage loads it first, so it behaves exactly like setBackgroundImage - you never get an error, only a delay.
To find out whether an image is ready, use isBackgroundImageLoaded:
if (manager.isBackgroundImageLoaded("bg1.jpg")) {
manager.showBackgroundImage("bg1.jpg");
}
The second version of showBackgroundImage places the image into the specified area of the screen instead of filling it completely. The coordinates are relative to the screen dimensions, so they do not depend on the video resolution: (0, 0, 1, 1) is the whole screen, (0.25, 0.25, 0.5, 0.5) is a centered quarter of it, and (0.5, 0, 0.5, 0.5) is the top right quarter:
manager.showBackgroundImage("bg1.jpg", 0.25, 0.25, 0.5, 0.5);
The rest of the background plane keeps the color set by setBackgroundColor. Whether the image is scaled to fit the area, cropped or repeated depends on the player, so check the result on the target devices.
Every preloaded image occupies memory until you release it. Players have a limited amount of memory for the background plane, so preloading many images and never releasing them may break the playback. Release the images you no longer need:
manager.flushBackgroundImage("bg1.jpg");
manager.flushBackgroundImages();
The first call releases one image, the second one releases all of them. A released image can be preloaded again at any time.