Using Subtitle Graphic Tutorial

This document gives you more information about how to use Subtitle Graphic.

Purpose

Subtitle Graphic displays subtitles on the screen when you use two different drawing modes:

  • swap frame mode

  • draw frame mode

Required background

Subtitle Graphic is loaded by Video Player Controller to render subtitle graphics on a window when subtitle is added to a video screen.

Introduction

Subtitle Graphic (CMMFSubtitleGraphic) takes bitmap handles to display subtitles on the window. The bitmap handle must be a transparent bitmap. The bitmap handle contains the subtitle image to render on the top of the video window. The bitmap handle must be the same size as the subtitle region.

Using Subtitle Graphic

The following task is done using Subtitle Graphic:

Basic procedure to use Subtitle Graphic

The high-level steps to use Subtitle Graphic are as follows:

  • To create a new CMMFSubtitleGraphic call CMMFSubtitleGraphic::NewL().

  • To get the graphic identity of the created CMMFSubtitleGraphic call CMMFSubtitleGraphic::GetId(TWsGraphicId &).

    Note: If multiple window support is required, multiple Subtitle Graphics can be created at the same time, and each Subtitle Graphic will have a different graphic ID. Each instance of CMMFSubtitleGraphic can be used for one window.

  • To draw to CMMFSubtitleGraphic there are two drawing modes:

    • Swap frame mode

      CMMFSubtitleGraphic::Initialize(TInt, TInt) initialises the CRP with two bitmap handles, which act as a front buffer and a back buffer. To swap the current drawing bitmap call CMMFSubtitleGraphic::SwapFrame().

      The example below shows Subtitle Graphic swap frame mode:

      
      
      // initialize crp with the specified bitmap handles
      crp->Initialize(bitmap1.Handle(), bitmap2.Handle()); 
      
      <snip> decode first frame into bitmap1 here… <snip>
      
      // display drawrect1 of bitmap1 for displayDuration number of microsecond
      crp->SwapFrame(1, drawRect1, displayDuration); 
      
      <snip> decode second frame into bitmap2 here… <snip>
      
      // display drawrect2 of bitmap2 for displayDuration number of microsecond
      crp->SwapFrame(2, drawRect2, displayDuration); 
      
      <snip> decode third frame into bitmap1 here… <snip>
      
      // display drawrect1 of bitmap1 for displayDuration number of microsecond
      crp->SwapFrame(1, drawRect1, displayDuration); 
      
      
    • Draw frame mode

      CMMFSubtitleGraphic::Initialize() initialises the CRP with no bitmap handles. To draw bitmap call CMMFSubtitleGraphic::DrawFrame().

      The example below shows Subtitle Graphic draw frame mode:

      
      
      // initialize crp for drawing any bitmap handle
      crp->Initialize(); 
      
      <snip> decode first frame into bitmap1 here… <snip>
      
      // draw drawrect1 of bitmap1 for displayDuration number of microsecond
      crp->DrawFrame(bitmap1.Handle(), drawRect1, displayDuration); 
      
      <snip> decode second frame into bitmap2 here… <snip>
      
      // draw drawrect2 of bitmap2 for displayDuration number of microsecond
      crp->DrawFrame(bitmap2.Handle(), drawRect2, displayDuration);
      
      

    In both of the examples above, the drawRect1 and drawRect2 represent the region of the bitmap that contains the subtitle. The region is relative to the bitmap. The region is sent to indicate the region of the bitmap that needs to be drawn. The displayDuration is the time that the subtitle bitmap will be displayed before it is cleared. If the value is 0, the subtitle bitmap will not be cleared until the next DrawFrame(), SwapFrame(), or Clear() call.

  • To clear Subtitle Graphic call CMMFSubtitleGraphic::Clear(). This may be used when a video is stopped to remove the clear the subtitle bitmap from window.