</codeblock> <p>This method opens the video clip from a file. It uses an optionally specified plug-in in the argument to load a controller. If no controller plug-in is specified, it searches through the list of available plug-ins and attempts to use each one until successful or the end of the list is reached. </p> <p> <b>Note:</b> There is also another method to open a video clip from a file. It is strongly recommended to use this method. </p> <codeblock id="GUID-C708A76D-0156-5106-B288-BFF6563A15F8" xml:space="preserve">OpenFileL(const TMMSource&amp; aSource, TUid aControllerUid);</codeblock> <p>Where <codeph>aSource</codeph> is a filename or an open handle to a file containing the video clip and <codeph>aControllerUid</codeph> is an optionally specified plug-in. If specified, it will force the video player to use the controller with the given UID. If no controller plug-in is specified, this function searches through a list of all available plug-ins and attempts to use each one until successful or the end of the list is reached. </p> </li> <li id="GUID-E6A42E5B-685A-54FD-B6D0-B9ABED940F63"><p> <b>From a descriptor</b>  </p> <codeblock id="GUID-E53E70E6-FD54-5AB8-AC5D-F1EA6F86A9C6" xml:space="preserve">OpenDesL(const TDesC8&amp; aDescriptor, TUid aControllerUid=KNullUid);</codeblock> <p>This method opens the video clip from a descriptor. It opens the video clip contained as binary data in a descriptor using an optionally specified plug-in in the argument to load a controller. If no controller is specified, it searches through the list of available plug-ins and attempts to use each one until successful or the end of the list is reached. </p> </li> <li id="GUID-01F9EE80-BBA3-5E92-A14D-E749003D332C"><p> <b>From an URL</b>  </p> <codeblock id="GUID-4C942ECA-1308-597B-8F6A-BE942222D53A" xml:space="preserve">OpenUrlL(const TDesC&amp; aUrl, TInt aIapId = KUseDefaultIap, const TDesC8&amp; aMimeType=KNullDesC8, TUid aControllerUid=KNullUid);</codeblock> <p>This method opens the video clip from the specified URL and identified by the MIME type. In addition a plug-in can be specified if necessary. If no controller plug-in is specified, this function searches through a list of all available plug-ins and attempts to use each one until successful or the end of the list is reached. </p> </li> </ul> <p>Once the opening of the video clip is complete, successfully or otherwise, the callback function <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>MVideoPlayerUtilityObserver::MvpuoOpenComplete()</apiname></xref> is called. This notifies the client whether the video clip was successfully opened or not. </p> <p> <b>Note:</b> Opening a video source must be done before providing any window destination. This is because the controller needs to be able to support graphics surfaces and this is only known at load time. </p> <p id="GUID-C984C913-6647-50E6-A30D-CAA41E6EE1B0"><b>Adding a Display</b> </p> <p>To play video on graphics surfaces without an associated target window you need to add a display. The high level steps to add a specified display are shown here: </p> <ul><li id="GUID-C7295586-EDEB-5DF3-A02F-B1CF5DE12215"><p>Call the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::AddDisplayL()</apiname></xref> method. This method takes a window server session, which is used to register the graphics surface, the display ID of the display that the surface is to be placed on, and a reference to a surface event handler. </p> <codeblock id="GUID-58633CE4-34E0-5780-8D13-A94B9CBA13EE" xml:space="preserve">IMPORT_C void AddDisplayL(RWsSession&amp; aWs, TInt aDisplay, MMMFSurfaceEventHandler&amp; aEventHandler);</codeblock> <p> <b>Note</b>: To use windowless graphics surfaces, you must provide an implementation of the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>MMMFSurfaceEventHandler</apiname></xref> interface. The <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>MMMFSurfaceEventHandler</apiname></xref> interface handles surface-related events from the MMF. </p> </li> </ul> <p id="GUID-3DBD0CE2-3351-5ED5-AB26-4976848E3B39"><b>Preparing to Play Video Data</b> </p> <p>The high level steps to prepare to play video are shown here: </p> <ol id="GUID-344888A8-4F8A-5481-8252-37E181FC1BEF"><li id="GUID-8E6DDFD9-583B-5B51-A3FF-15F567F5C743"><p>Once the video data is ready, call the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::Prepare()</apiname></xref> function. </p> </li> <li id="GUID-17137AFF-1E24-5A0D-9DD9-19B353A4209E"><p>When the client receives the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>MVideoPlayerUtilityObserver::MvpuoPrepareComplete()</apiname></xref> callback, the video player utility will be in configured state. </p> </li> </ol> <p id="GUID-87F516DC-090E-57F9-B140-B4702F44E391"><b>Making Configuration Adjustments</b> </p> <p>Once the video clip is open and ready to play, configuration adjustments can be made using the following functions: </p> <ul><li id="GUID-E379C3CD-6117-53B9-BF0F-E78303D1A618"><p> <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::AddDisplayWindowL</apiname></xref>: This function adds a new window for displaying the video picture. Client applications must use this method instead of <codeph>SetDisplayWindowL()</codeph> when using <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2</apiname></xref>. This method has two overloads: </p> <ul><li id="GUID-C3098C44-63D5-56C3-9568-0BB5DE2EF41D"><p>The first takes window clipping and video extent as parameters: </p> <codeblock id="GUID-9F0B2B54-F376-5B3A-B2C5-C07E070496AC" xml:space="preserve">AddDisplayWindowL(RWsSession&amp; aWs, CWsScreenDevice&amp; aScreenDevice, RWindowBase&amp; aWindow, const TRect&amp; aVideoExtent, const TRect&amp; aWindowClipRect);</codeblock> </li> <li id="GUID-B9F7DDF9-A2CF-5249-85A4-1F62ED831637"><p>The second is a simplified version which doesn't take window clipping and video extent as parameters: </p> <codeblock id="GUID-5EACD930-7DA3-5FCB-8C16-5F1EDD04F9C4" xml:space="preserve">AddDisplayWindowL(RWsSession&amp; aWs, CWsScreenDevice&amp; aScreenDevice, RWindowBase&amp; aWindow);</codeblock> <p> <b>Note:</b> When using this version, the video extent and window clipping rectangle default to the whole window. </p> </li> </ul> </li> <li id="GUID-B6ECCA94-FA08-539C-BF86-8684BB34E972"><p> <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::SetVideoExtentL</apiname></xref>: This function sets the video extent on the screen, relative to the window. The extent specifies the area of screen in which the video picture is placed and may be partially or completely outside of the video window. Video picture position within the extent depends on the picture size and content alignment or offset. </p> <codeblock id="GUID-02EDD632-ED30-50B9-B4F3-11A304FDF75C" xml:space="preserve">SetVideoExtentL(const TRect&amp; aVideoExtent);</codeblock> <p> <b>Note:</b> Video extent can be set before a successful call to <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>AddDisplayWindowL</apiname></xref> has been made. </p> </li> <li id="GUID-155740FA-08F7-5429-A2EE-B912D467EF64"><p> <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::SetWindowClipRectL</apiname></xref>: This function sets the window clipping rectangle, relative to the window. The clipping rectangle specifies the part of the window used to display the video picture and must be fully contained within the window. Any video content falling outside of this area is not displayed. </p> <codeblock id="GUID-F360165D-1E13-5ABE-8D2E-3818B32B139C" xml:space="preserve">SetWindowClipRectL(const TRect&amp; aWindowClipRect);</codeblock> </li> </ul> <p id="GUID-6D7BD5B1-DDD0-5963-AF84-8169BD4D6CC3"><b>Playing Video Data</b> </p> <p>The high level step to play video data is shown here: </p> <ul><li id="GUID-89BDC30D-CE13-5A9C-B348-AA46D751B80A"><p>After configuring the properties, the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::Play()</apiname></xref> function is called for the video clip to be played. </p> </li> </ul> <p id="GUID-97516B18-D59B-5FA2-9881-2FE3025AE888"><b>Replacing a Surface</b> </p> <p>If <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CMMFVideoPlayerUtility2</apiname></xref> receives a <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>ReplaceSurface</apiname></xref> event, then the graphics surface needs to be replaced. The high level steps to replace a surface are shown here: </p> <ol id="GUID-A1A1CEE4-775E-5A3B-81FC-FAC2C6A6AEDF"><li id="GUID-24FB37D7-FC3A-57B8-AF88-2A01450BA623"><p>Call <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::RemoveDisplay()</apiname></xref> and set <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>aDisplay</apiname></xref> to be the ID of the display to remove. </p> <codeblock id="GUID-91A4F673-DE4A-5A78-976F-B90D4D1136F1" xml:space="preserve">IMPORT_C void RemoveDisplay(TInt aDisplay);</codeblock> </li> <li id="GUID-216C4BF6-809F-50C7-BCE5-704C15692A92"><p>Call <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::AddDisplayL()</apiname></xref>. This method takes a window server session, which is used to register the graphics surface, the display ID of the display that the surface is to be placed on, and a reference to a surface event handler. </p> <codeblock id="GUID-3B6FFFA5-0EA7-51B6-840E-BB3174F07662" xml:space="preserve">IMPORT_C void AddDisplayL(RWsSession&amp; aWs, TInt aDisplay, MMMFSurfaceEventHandler&amp; aEventHandler);</codeblock> </li> </ol> <p id="GUID-FB26B528-1FBB-5A6E-B33B-7368A9596DAF"><b>Stopping Video Playback</b> </p> <p>The high level steps to stop video playback are shown here: </p> <ol id="GUID-4D4C9ACD-1BDE-5F65-A1A7-3603EB87C6E1"><li id="GUID-1C696A16-E514-50C0-BFB1-BB55ADC21299"><p>Call the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::Stop()</apiname></xref> function. </p> <codeblock id="GUID-C2275FD7-7AAF-5D7E-9736-855BE9BAC2BE" xml:space="preserve">IMPORT_C TInt Stop();</codeblock> <p>Video playback is stopped as soon as possible, and the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>MVideoPlayerUtilityObserver::MvpuoPlayComplete()</apiname></xref> callback function is called. </p> </li> <li id="GUID-46E456E9-71A5-531D-BA40-47AB20106263"><p>To remove a display from the list of surface rendering targets, call <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::RemoveDisplay()</apiname></xref> and set <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>aDisplay</apiname></xref> to be the ID of the display to remove: </p> <codeblock id="GUID-96BD89C8-0DFE-5D24-AD74-6BC8A893794C" xml:space="preserve">IMPORT_C void RemoveDisplay(TInt aDisplay);</codeblock> <p>Calling <codeph>RemoveDisplay()</codeph> destroys any graphics surface associated with the display. You must make sure the graphics surface can be safely destroyed before making this call. </p> <p> <b>Note</b>: If you have added windows to the display using <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::AddDisplayWindowL()</apiname></xref>, then the graphics surface can only be destroyed when you have removed all of the windows as well. That is, when no windows or event handlers are using the display. To remove a window, use the <xref href="GUID-42D1182F-46D8-3C78-8D3C-C1BB465FCA1F.dita"><apiname>CVideoPlayerUtility2::RemoveDisplayWindowL()</apiname></xref> function. </p> </li> </ol> </section> <section><title>See Also</title> <p><xref href="GUID-3F0856D9-7B58-5519-9B26-97F1A035E21D.dita">Video Player Utility Tutorials</xref>  </p> </section> </conbody></concept>