Using video overlays

Creating a video overlay

To create a video overlay:

1. Create a new MIDlet and set it to support video overlays by specifying the Nokia-UI-Enhancement JAD attribute as follows:

   Nokia-UI-Enhancement: VideoOverlaySupported

   This attribute value instructs the Java Runtime to render graphics primitives on top of video content if they are drawn with Canvas.paint. If you do not specify this attribute value, video content is displayed on top of any overlapping graphics drawn with the Canvas.paint method, thereby hiding the graphics.

2. In the MIDlet main class, display the UI component that contains the video content and overlay. The following code snippet creates a new VideoCanvas object and displays it at MIDlet startup. Displaying the VideoCanvas object starts a video player and generates a call to the VideoCanvas.paint method, which renders the overlay graphics on top of the video player.

   // display a VideoCanvas when the MIDlet starts
   public void startApp() {
       VideoCanvas videoCanvas = new VideoCanvas();
       Display.getDisplay(this).setCurrent(videoCanvas);
   }

3. Implement the UI component on which the video content and overlay are rendered. The following code snippet creates the framework for a custom Canvas class called VideoCanvas.

   // import the necessary packages and classes
   import java.io.InputStream;
   import java.io.IOException;
   import javax.microedition.lcdui.Canvas;
   import javax.microedition.lcdui.Graphics;
   import javax.microedition.media.*;
   import javax.microedition.media.control.VideoControl;
   import com.nokia.mid.ui.DirectGraphics;
   import com.nokia.mid.ui.DirectUtils;
   
   public class VideoCanvas extends Canvas {
   
       // create a Player and a VideoControl for the video content
       // ... (see step 4 of this example)
   
       // implement the paint() method for rendering the video overlay
       // ... (see steps 5-8 of this example)
   
   } // end class VideoCanvas

4. Create a Player for the video content, and create a VideoControl for managing how the video content is displayed. The following code snippet creates a Player for playing back a video file, creates a VideoControl for the Player, and assigns the VideoControl to VideoCanvas.

   private Player player;
   private VideoControl videoControl;
   
   try {
       // create a video Player
       InputStream in = getClass().getResourceAsStream("video.3gp");
       player = Manager.createPlayer(in, "video/3gpp");
       player.realize();
       player.prefetch();
       // create a VideoControl for the video Player
       videoControl = (VideoControl)player.getControl("VideoControl");
       // display the video on VideoCanvas and start playback
       if (videoControl != null) {
           videoControl.initDisplayMode(VideoControl.USE_DIRECT_VIDEO, this);
           videoControl.setVisible(true);
           player.start();
       }
   } catch (IOException e) {
   } catch (MediaException e) {
   }

5. To render the video overlay, implement the Canvas.paint method. The following code snippet creates the framework for the VideoCanvas.paint method. The Graphics parameter is used for rendering the video overlay on VideoCanvas.

   // render the video overlay by drawing on Graphics g
   protected void paint(Graphics g) {
   
       // store the dimensions of the displayable area of VideoCanvas
       int displayableWidth = this.getWidth();
       int displayableHeight = this.getHeight();
   
       // store the video dimensions
       int videoWidth  = videoControl.getDisplayWidth();
       int videoHeight = videoControl.getDisplayHeight();
   
       // store the video position relative to VideoCanvas
       int videoX = videoControl.getDisplayX();
       int videoY = videoControl.getDisplayY();
   
       // clear the video overlay area that lies outside the video area
       // ... (see step 6 of this example)
   
       // optionally, set the video overlay to semi-transparent
       // ... (see step 7 of this example)
   
       // draw the video overlay content
       // ... (see step 8 of this example)
   
   } // end paint()

6. In the paint method, clear the video overlay area that lies outside the video area.

   

   Figure: Video area and video overlay area

   The following code snippet uses the Graphics.fillRect method to fill the video overlay area around the video area with black.

   // set the rendering color for the video overlay to black
   g.setColor(0);
   // clear the extra video overlay area by filling it with the rendering color
   g.fillRect(0, 0, videoX, displayableHeight);
   g.fillRect(videoX + videoWidth, 0, displayableWidth, displayableHeight);
   g.fillRect(0, 0, displayableWidth, videoY);
   g.fillRect(0, videoY + videoHeight, displayableWidth, displayableHeight);

7. If you want to create a semi-transparent video overlay, specify an alpha channel value for the overlay graphics, or use an image file that already contains an alpha channel. The following code snippet converts the Graphics object of the paint method to a DirectGraphics object, and calls the DirectGraphics.setARGBColor method to set the alpha channel value and rendering color for the video overlay.

   // set the alpha level (8F) and rendering color (00FFFF) for the video overlay
   DirectGraphics dg = DirectUtils.getDirectGraphics(g);
   dg.setARGBColor(0x8F00FFFF);

8. In the paint method, draw the video overlay content. The following code snippet draws a PNG image on the video overlay by calling the Graphics.drawString method. When the Canvas.paint method renders the video overlay, the image is displayed over the video content.

   // Create an Image
   InputStream is = getClass().getResourceAsStream("image.png");
   Image overlay = Image.createImage(is);
   // Draw the Image at the center of the video area
   g.drawImage(overlay, videoX + videoWidth/2, videoY + videoHeight/2, Graphics.VCENTER | Graphics.HCENTER);

Using video overlays correctly

When creating video overlays, note the following:

• After you have added the video Player and called its start method, clear the video area by generating an empty paint on the Canvas. To generate an empty paint, call the Canvas.repaint method and ensure that it triggers a Canvas.paint operation where nothing is drawn. This clears any previous content covering the video area. For an example on how to generate an empty paint, see the VideoOverlayMIDlet.

• To ensure that no portion of the previous screen is shown when the video player is loaded, clear the area outside the video area by calling Graphics.fillRect from Canvas.paint. Do not call Graphics.fillRect on the video area, since this hides the video player.

• To avoid sluggishness during high-quality video playback, do not repaint the Canvas frequently.

• To remove a previously rendered video overlay from the video area, repaint the Canvas so that nothing is drawn on the video area.

• You can only render video overlays on Canvas-based objects. You cannot use video overlays on, for example, GameCanvas, CustomItem, Form Item, or on top of animated GIFs.

Example: VideoOverlayMIDlet

To download a full example MIDlet that shows you how to create video overlays for video playback and for taking pictures with the device camera, click here. The download includes the Eclipse project files for the MIDlet and the JAD and JAR files for installing the MIDlet onto a device.