Using Subtitle Graphic Tutorial

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:

How to use 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.