<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task xml:lang="en" id="GUID-152BF5C3-CE32-5174-A043-1B2D5D8168C3"><title>Media Client Video Display Tutorial</title><shortdesc>This tutorial introduces how to use the Media Client Video Display library for different functions. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody><prereq id="GUID-5651699A-CC2F-514F-848E-5FF6B8F5F886"><p>Before you start: </p> <ul><li id="GUID-536C284E-1CFE-525A-9D4C-DCF5B3DD653C"><p>Understand the <xref href="GUID-2DC80BA9-7AA2-5CD3-9105-1DE28CE196C1.dita">Video Client Overview </xref>. </p> </li> <li id="GUID-843063AD-E283-5681-9677-89C030EAC581"><p>Understand the concept of <xref href="GUID-B54E84A4-2F81-57C2-BEDC-48C6B3F6A023.dita">Video Player Utility 2 Tutorials </xref>. </p> </li> </ul> </prereq> <context id="GUID-04B39912-E914-547C-B974-BBEFD297819E"><p>The <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita"><apiname>CMediaClientVideoDisplay</apiname></xref> class is used to provide video display functionality for the video client APIs. The <codeph>CMediaClientVideoDisplay</codeph> class allows you to use as a standalone video display APIs from the client utilities. </p> </context> <steps-unordered id="GUID-6CAAFEE1-F967-5631-A6FD-AD9686DD92A7"><step id="GUID-7E21CFFA-72DA-51F8-9AAC-A3A9F8EA0E36"><cmd/><info>  Displaying video data  </info> <info>To display new video data on a window, call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-6D68FC67-9CA5-3ABD-9836-E4C630F4EAE8"><apiname>CMediaClientVideoDisplay::NewL(TInt)</apiname></xref> to initialize a new instance of the video client data. </info> <info>If you have already created the graphics surface with <codeph>TSurfaceId</codeph>, you must call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-32393101-A81D-3E77-865F-906C5C49AFBF"><apiname>CMediaClientVideoDisplay::NewL(TInt,const TSurfaceId &amp;,const

                TRect &amp;,TVideoAspectRatio)</apiname></xref> to intialize a new instance of the video client data. </info> </step> <step id="GUID-020D0B83-A5DF-5A4D-BC36-233506158D61"><cmd/><info> Assigning values to the video surface parameters  </info> <info>Call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-1E6476BF-0D49-3B89-A46E-12A25C235D0A"><apiname>CMediaClientVideoDisplay::SurfaceCreated(const

                TSurfaceId &,const TRect &,TVideoAspectRatio,const TRect

                &amp;)</apiname></xref> to assign values to the following video surface parameters: </info> <substeps id="GUID-B9C8B568-85EC-5FCA-B936-3D6CB5364342"><substep id="GUID-5236372A-78CB-5ACE-9441-7CA92184E316"><cmd/><info>Surface ID (Identity) </info> </substep> <substep id="GUID-42C01E46-B169-5385-9698-B264919D0025"><cmd/><info>Dimensions of the crop rectangle for the video image </info> </substep> <substep id="GUID-47AF38B4-8BF0-515C-B977-EBDE78A69174"><cmd/><info>Pixel aspect ratio that is defined by the <xref href="GUID-1D3336FD-853E-3AD4-8F82-4A066F1C3F16.dita"><apiname>TVideoAspectRatio</apiname></xref> function. </info> </substep> <substep id="GUID-B352BD3C-9980-55C4-B4E0-406780EE8A3C"><cmd/><info>Dimensions of the crop region for the video image </info> </substep> </substeps> <info>If the video surface parameter changes, you can call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-EAF9E995-8A54-34FB-8D65-0ECDDB90C2AF"><apiname>CMediaClientVideoDisplay::SurfaceParametersChanged(const TSurfaceId

                &amp;,const TRect &amp;,TVideoAspectRatio)</apiname></xref> to assign the changed values. </info> </step> <step id="GUID-8CFFA728-593B-5395-B0FA-F78F1BCF9D28"><cmd/><info> Removing the graphics surface  </info> <info>Call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-E884FCBE-7A8C-3C2C-A731-75CED072FF93"><apiname>CMediaClientVideoDisplay::RemoveSurface()</apiname></xref> to remove the graphics surface that is not needed for the video display. </info> </step> <step id="GUID-315A56C1-CA80-5FCB-85B2-2310E0344B30"><cmd/><info> Adding a new window  </info> <info>Call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-17152DEB-CC1D-364F-8410-A3A75EF0F1CA"><apiname>CMediaClientVideoDisplay::AddDisplayWindowL(const

                RWindowBase *,const TRect &,const TRect &,const TRect

                &,TReal32,TReal32,TVideoRotation,TAutoScaleType,TInt,TInt,RWindow

                *)</apiname></xref> to add a new window for displaying the video picture. </info> </step> <step id="GUID-DBBC17CD-34AE-5B0A-BF4C-80DC081F57D0"><cmd/><info> Redrawing the window  </info> <info>Call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-BBCDE8A8-0224-3493-BC95-675F376ECE63"><apiname>CMediaClientVideoDisplay::RedrawWindows(const TRect

                &amp;)</apiname></xref> to redraw all the windows with new crop region. </info> </step> <step id="GUID-976C1F80-1BC9-5419-8E23-48D182499D0D"><cmd/><info>  Setting the video data for automatic scaling   </info> <info>To set the video data for automatic scaling: </info> <substeps id="GUID-96791692-1CDC-5B3C-8C65-96D78C6F8B95"><substep id="GUID-D42089A3-BCED-59C5-9C0F-DA4334657424"><cmd/><info>If the new window is displayed, you can then call the <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-AC2CC1B8-4FAA-3DCB-A06E-E40FC045C1D8"><apiname>CMediaClientVideoDisplay::SetAutoScaleL(const RWindowBase

                     &amp;,TAutoScaleType,TInt,TInt,const TRect &amp;)</apiname></xref> function. </info> <info>When automatic video scaling is active, the video image is scaled automatically to match the video window, based on the scaling type, and positioned according to the video data parameters. </info> <info> Note: All video controller do not support automatic scaling. </info> </substep> <substep id="GUID-C8E3293B-783D-5899-9BA6-06748FC9A7EC"><cmd/><info>When the video data is already opened, you can call the <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-505F47B8-017D-3986-B736-A5A792E4EB1D"><apiname>CMediaClientVideoDisplay::SetAutoScaleL(TAutoScaleType,TInt,TInt,const

                     TRect &amp;)</apiname></xref> function. </info> <info>This function related to the function <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita#GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F/GUID-0E2F30EE-470C-306D-991A-2C9FF9EA53D6"><apiname>CVideoPlayerUtility2::SetAutoScaleL(const RWindow

                     &amp;,TAutoScaleType)</apiname></xref> in <codeph>CVideoPlayerUtility2</codeph>. </info> </substep> </substeps> </step> <step id="GUID-A3B52D02-956C-59EA-868B-0D1A0341AC7C"><cmd/><info> Setting the video data for specified scaling  </info> <info>To scale the video image for a specified dimension from its original size within the window: </info> <substeps id="GUID-9A73D43A-6442-54BC-B440-FD4F3A746A0C"><substep id="GUID-8652B266-1BB1-5C6A-8BAD-DDB163BEFB38"><cmd/><info>If you open a new window, you can then call the <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-521D0999-54A6-32A8-889E-1350EA329055"><apiname>CMediaClientVideoDisplay::SetScaleFactorL(const RWindowBase

                     &amp;,TReal32,TReal32,const TRect &amp;)</apiname></xref> function. </info> </substep> <substep id="GUID-8797660F-EE6E-5B39-8DBE-6D1A950F6894"><cmd/><info>When the video clip is already opened, you can then call the <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-AA3EF745-AE8E-3542-ADDD-83137C936C48"><apiname>CMediaClientVideoDisplay::SetScaleFactorL(TReal32,TReal32,TBool)</apiname></xref> function. </info> </substep> </substeps> </step> <step id="GUID-8B2D922A-2B36-5D76-909B-ED4FB7479B12"><cmd/><info> Retrieving the scale feature  </info> <info>Call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-A3C8860D-1543-32A1-8B7F-76EE5244A042"><apiname>CMediaClientVideoDisplay::GetScaleFactorL(const

                RWindowBase &amp;,TReal32 &amp;,TReal32 &amp;)</apiname></xref> to retrieve the scale feature currently set for a window. </info> <info>This function is preferred to use with <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2</apiname></xref>. </info> </step> <step id="GUID-934AA6AD-61C2-5011-8822-CB64FCB2A0D6"><cmd/><info> Rotating the video image  </info> <info>To rotate the video image within the window: </info> <substeps id="GUID-9B8DD422-3E6F-501D-A3F4-9346ABBCD949"><substep id="GUID-DC485027-3710-5FC9-AEBE-855BD830D0A7"><cmd/><info>If the new window is displayed, you can then call the <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-9CEEAEDA-8644-32CF-B99F-20F3DFD17AB8"><apiname>CMediaClientVideoDisplay::SetRotationL(const RWindowBase

                     &amp;,TVideoRotation,const TRect &amp;)</apiname></xref> function. </info> </substep> <substep id="GUID-16F9CD4D-27F5-5B34-8804-EC822CF51258"><cmd/><info>When the video data is already opened, you can call the <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-5CDEB3B0-3995-3943-B924-A17B7CFC64EF"><apiname>CMediaClientVideoDisplay::SetRotationL(TVideoRotation,const TRect

                     &amp;)</apiname></xref> function. </info> </substep> </substeps> <info>Both the rotation functions can replace the function <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita#GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F/GUID-0E906869-D5BD-3548-BEE3-8B4C46EDDF6C"><apiname>CVideoPlayerUtility2::SetRotationL(const RWindow

                &amp;,TVideoRotation)</apiname></xref> in <codeph>CVideoPlayerUtility2</codeph> and the function <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-8352B854-9B4F-37E9-9012-3F932F06ADF3"><apiname>CVideoPlayerUtility::SetRotationL(TVideoRotation)</apiname></xref> in <codeph>CVideoPlayerUtility</codeph>. </info> </step> <step id="GUID-7CE53CF1-0AF2-5205-955D-7846FB4CA860"><cmd/><info> Retrieving the rotation feature  </info> <info>Call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-23B20C1C-21C1-326B-85E9-2E1DD09455E7"><apiname>CMediaClientVideoDisplay::RotationL(const

                RWindowBase &amp;)</apiname></xref> to retrieve the video rotation set for a window. </info> <info>This function is preferred to use with <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2</apiname></xref>. </info> </step> <step id="GUID-8DC62749-D9DB-5DAC-819F-461DBB6D208E"><cmd/><info> Clipping the window  </info> <info>Call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-EED73482-1C5A-346D-978A-57914638DB26"><apiname>CMediaClientVideoDisplay::SetWindowClipRectL(const

                RWindowBase &amp;,const TRect &amp;,const TRect &amp;)</apiname></xref> to set the window clipping rectangle that is relative to the window. </info> </step> <step id="GUID-F8D597D1-1ECD-5E15-A542-566CAF46BD3D"><cmd/><info> Setting the video extension  </info> <info>Call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-1C883167-72AE-37B1-A5B7-4AF9C696D889"><apiname>CMediaClientVideoDisplay::SetVideoExtentL(const

                RWindowBase &amp;,const TRect &amp;,const TRect &amp;)</apiname></xref> to set the video extension on the screen that is relative to the window. </info> </step> <step id="GUID-523A2133-9E31-54D0-92E3-63D031D27254"><cmd/><info> Removing the window  </info> <info>Call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-B55A9003-4C22-38F3-AF23-7DE3A1B3E5B1"><apiname>CMediaClientVideoDisplay::RemoveDisplayWindow(const

                RWindowBase &amp;)</apiname></xref> to removes a window that is currently being used to display the video picture. </info> </step> <step id="GUID-4EE90AA5-91C8-5D31-97F1-696BE2695E32"><cmd/><info> Closing the video data  </info> <info>Call <xref href="GUID-2BE86C43-A982-39BC-B881-C190966A7E77.dita#GUID-2BE86C43-A982-39BC-B881-C190966A7E77/GUID-A0372F30-C805-340B-BC0F-635622FFFB26"><apiname>CMediaClientVideoDisplay::~CMediaClientVideoDisplay()</apiname></xref> to close the video data instance before you leave the <codeph>CMediaClientVideoDisplay</codeph> function. </info> </step> </steps-unordered> </taskbody><related-links><link href="GUID-3F0856D9-7B58-5519-9B26-97F1A035E21D.dita"><linktext>Video Player Utility

                Tutorials</linktext> </link> </related-links></task>