Update contrib.
1 // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
16 #ifndef DEVVIDEOSTANDARDCUSTOMINTERFACES_H
17 #define DEVVIDEOSTANDARDCUSTOMINTERFACES_H
20 #include <mmf/devvideo/devvideoplay.h>
23 MMmfVideoMediaProtected interface UID.
27 const TUid KUidMmfVideoMediaProtected = { 0x10273827 };
30 Used to notify a video rendering media device that the data can only be passed to a secure output.
31 Typically used for DRM-protected content and implemented on video decoding or post-processing media
32 device where insecure video outputs could be used.
36 class MMmfVideoMediaProtected
40 Notifies a media device if the content is protected, with the intent that it may only be sent to a secure output.
42 The device display is typically considered a secure output, but a high-quality unprotected analogue
43 or digital video output connector is not.
44 Once protection has been indicated, playback could fail when Start() is called or at any time
45 during playback. The failure is reported using MdvpoFatalError(KErrorOutputUnsecured), if the current output
46 has been switched to an insecure output.
48 @param aProtected Set to ETrue if the content can only be sent to a secure output,
49 EFalse if both secure and non-secure outputs can be used. By default all content can be sent to
50 both secure and insecure outputs. (aProtected == EFalse)
51 @leave KErrNotSupported Secure outputs are not supported. The client should not play protected content.
53 virtual void MmvsoMediaIsProtectedL(TBool aProtected) = 0;
56 /*****************************************************************************/
58 KUidMmfVideoInputSnapshot interface UID.
62 const TUid KUidMmfVideoInputSnapshot = { 0x10204beb };
64 The callback interface used by MMmfVideoInputSnapshot to notify snapshot completion.
68 class MMmfVideoInputSnapshotObserver
72 The callback method that the observer should implement to receive notifications
73 from the MMmfVideoInputSnapshot implementation.
74 @param aError One of the system wide error codes.
76 virtual void SnapshotComplete(TInt aError) = 0;
80 Single frame capture support for video recording media devices.
82 The interface is typically implemented in pre-processing and encoding media devices with direct capture support.
86 class MMmfVideoInputSnapshot
90 Sets the observer object to use for snapshot complete callbacks.
92 This method can be called both before and after the media device has been initialised with InitializeL().
93 It must be called before GetSnapshotL() is called for the first time.
94 @param aObserver A pointer to the observer object to use.
96 virtual void MmvisSetObserver(MMmfVideoInputSnapshotObserver* aObserver) = 0;
99 Grabs a duplicate of the next input frame. This method is asynchronous; the media device will call
100 MMmfVideoInputSnapshotObserver::SnapshotComplete() when the picture is available.
102 This method may only be called after the media device has been initialised with InitialiseL()
103 and after Start() has been called. The request can be cancelled with CancelSnapshot(). Some implementations
104 may not support format conversions or scaling for snapshot images.
106 @param aPictureData Target picture. The memory for the picture must be allocated by the caller and
107 initialised properly. The data formats must match the snapshot format requested.
108 @param aFormat A reference to the picture format structure that indicates the snapshot format to use.
110 @leave KErrNotSupported The requested data format or picture size is not supported.
112 @pre This method can only be called after the media device has been initialized with InitializeL()
113 and the MMmfVideoInputSnapshotObserver has been set.
115 virtual void MmvisGetSnapshotL(TPictureData& aPictureData, const TUncompressedVideoFormat& aFormat) = 0;
118 Cancels an outstanding snapshot request.
120 If there is no active request pending then this call is ignored.
122 virtual void MmvisCancelSnapshot() = 0;
125 /*****************************************************************************/
127 MMmfVideoPlayHWDeviceColourInfoCustomHeader interface UID.
131 const TUid KUidMmfVideoPlayHWDeviceColourInfoCustomHeader = { 0x10273828 };
134 Interface support for the HW Device Plug-in to supply colour space and pixel aspect ratio information to the controller
138 class MMmfVideoPlayHWDeviceColourInfoCustomHeader
142 Reads colour space data format information from a coded data unit. Returns the colour space, data
143 range and pixel aspect ratio used in the bitstream.
145 @param aDataUnitType The type of coded data unit that is contained in aDataUnit. If the data is a
146 simple piece of bitstream, use EDuArbitraryStreamSection.
147 @param aDataUnitEncapsulation The encapsulation type used for the coded data. If the data is a simple
148 piece of bitstream, use EDuElementaryStream.
149 @param aDataUnit The coded data unit, contained in a TVideoInputBuffer.
150 @param aYuvFormat Target data structure for data format information. The media device will fill the
151 iCoefficients, iPattern, iAspectRatioNum, and iAspectRatioDenum fields.
152 @leave KErrNotSupported The data is not in a supported format.
153 @leave KErrCorrupt The data appears to be in a supported format, but is corrupted.
155 virtual void MmvpciGetColourSpaceHeaderInfoL(TVideoDataUnitType& aDataUnitType,
156 TVideoDataUnitEncapsulation& aDataUnitEncapsulation,
157 TVideoInputBuffer* aDataUnit, TYuvFormat& aYuvFormat) = 0;
160 /*****************************************************************************/
162 MMmfVideoHwDevClientNotifier interface UID.
166 const TUid KUidMmfVideoHwDevVideoPolicyExtension = {0x101FBFC3};
169 This class needs to be inherited by the video client. This is so that the video client will
170 receive a notification if its access has been revoked.
174 class MMmfVideoHwDevClientNotifier
178 Method to allow notification to the video client that their access to the video driver has been
179 revoked and their access to the video resources has already been removed. VideoAccessRevoked can
180 be called anytime after Initialize() has been called.
182 Once called it means that the video client should no longer be inputting any data.
183 The only thing the video client can do at this stage is destroy the MDF plug-in.
185 virtual void MmvhcnVideoAccessRevoked() = 0 ;
188 Method to allow notification to the video client that they need to release the video resources.
189 This allows the client slightly more control over their release process behaviour.
191 ReleaseVideoResource can be called anytime after Initialize has been called. Once called it
192 means that the video client needs to either call InputEnd() or Stop() to release the video resource
194 virtual void MmvhcnReleaseVideoResource() = 0;
199 Custom extension to allow MMF controller to set video policy priority preference.
201 Acceptable Priorities range from -100 to 100.
206 class MMmfVideoHwDeviceVideoPolicyExtension
210 Video client should call this function so that the MDF plugins will have a handle to the video client.
211 This is required so that the MDF plugin can notify the video client if their access has been revoked.
213 @param aClient Pointer to the video client
215 virtual void MmvhvpeSetVideoClient(MMmfVideoHwDevClientNotifier* aClient) = 0;
218 Allows the video client to specify the video priority they wish their process to have for their
219 video request. This may or may not be honoured depending upon the client process's platform security capabilities.
221 @param aPriority Preferred priority for video processing into the video manager.
223 virtual void MmvhvpeSetVideoPriority(TInt aPriority) = 0;
226 /*****************************************************************************/
228 MMmfVideoBufferManagement interface UID.
233 const TUid KUidMmfVideoBufferManagement = {0x10204bea};
236 An observer class for the buffer management custom interface, MMmfVideoBufferManagement.
237 Clients and source media devices using the interface must implement this class.
242 class MMmfVideoBufferManagementObserver
246 Notifies the observer that one or more new input buffers are available. The client can then
247 use MMmfVideoBufferManagement:: MmvbmGetBufferL() to get a buffer.
249 virtual void MmvbmoNewBuffers() = 0;
252 Notifies the observer all outstanding input buffers must be released immediately. The client
253 must synchronously call MMmfVideoBufferManagement:: MmvbmReleaseBuffer() for each of the buffers
254 it has allocated but not returned before returning from this method. It is intended that this method
255 is used when the target media device loses access to the buffers, as a result of a Direct Screen Access
256 abort, resource management override, or media device destruction.
258 virtual void MmvbmoReleaseBuffers() = 0;
262 Enables target media devices to allocate input data buffers for uncompressed data.
264 Client applications and source media devices can therefore write the input data directly
265 into a suitable memory area that the target media device can use, possibly eliminating one extra
266 memory copy from the data path. This is especially important with hardware implementations, where the
267 target hardware may only have access to specially allocated memory that only the media device can allocate.
269 The interface is typically implemented in pre-processing, encoding, and post-processing media devices.
270 It is mainly used for video encoder memory buffer input in applications like video editors and when
271 using hardware-accelerated post-processors with software video decoders.
276 class MMmfVideoBufferManagement
280 Used to signal the buffer options used.
286 The number of input buffers that the media device has. This is the number of buffers the
287 client can request through GetBufferL() before writing any back.
289 TUint iNumInputBuffers;
292 Buffer size in pixels. This should match the input data picture size, optionally with padding to
293 meet coding standard requirements.
299 Sets the observer object to use. The observer gets notified when new buffers are available
300 and when buffers need to be released back to the media device.
302 This method can only be called before the media device has been initialised with InitializeL().
304 @param aObserver The observer object to use.
306 virtual void MmvbmSetObserver(MMmfVideoBufferManagementObserver* aObserver) = 0;
309 Enables input buffer management mode. In buffer management mode the target media device allocates
310 memory for input buffers and the client can only use input buffers allocated with GetBufferL().
312 This method can only be called before the media device has been initialised with InitializeL().
313 This method must be called if the client uses GetBufferL().
315 @param aEnable ETrue if input buffer management mode is used.
317 virtual void MmvbmEnable(TBool aEnable) = 0;
320 Sets the buffer options to use. The client can request the number of input buffers that should
321 be available, but typically only few (one or two) buffers can be used.
323 This method can only be called before the media device has been initialised with InitializeL().
325 @param aOptions The buffer options to use.
328 @leave KErrNotSupported The requested buffer options are not supported. Typically the client
329 has requested too many input buffers.
331 virtual void MmvbmSetBufferOptionsL(const TBufferOptions& aOptions) = 0;
334 Gets the buffer options currently in use.
336 This method can only be called before the media device has been initialised with InitializeL().
338 @param aOptions Target buffer options data structure.
340 virtual void MmvbmGetBufferOptions(TBufferOptions& aOptions) = 0;
343 Gets a new input picture buffer. The client can then write data into the buffer and write it back
344 to the media device with WritePictureL(). After the media device has processed the TVideoPicture and
345 no longer needs any data from the buffer, it will notify the client by calling ReturnPicture().
347 This method can only be called after the media device has been initialised with InitializeL(). This
348 method can only be called in buffer management mode, i.e. if the client has called Enable(ETrue).
350 Note that target-allocated and client-allocated input buffers cannot be mixed. In buffer management mode
351 only input buffers allocated with this method can be sent to the media device.
353 If a client has retrieved buffers with GetBufferL(), it must be prepared to release them synchronously at
354 any point if MmmfBufferManagementObserver::ReleaseBuffers() is called. This may happen if the target media
355 device suddenly loses access to the buffers due to DSA abort, resource management conflict, or media device
358 The returned TVideoPicture object will have iHeader and iLayerBitRates set to NULL. The client can
359 allocate memory for those fields, and any data they may contain (such as TVideoPictureHeader::iOptional)
360 and set the pointers accordingly before writing the buffer back to the target media device. The memory must
361 remain valid and accessible until the media device returns the buffer with ReturnPicture(), at which time the
362 client can free or reuse the memory.
364 @param aSize The requested buffer size, in pixels. The buffer size should match the picture size set at
365 initialisation phase, or otherwise a suitable buffer may not be available. If the size is smaller than
366 the size set at initialisation phase, the allocated buffer may be larger than requested.
368 @return A new input picture buffer. If no free buffers are available, the return value is NULL.
370 @leave KErrGeneral The method will leave only if an error occurs. Note: Lack of free buffers is not
373 virtual TVideoPicture* MmvbmGetBufferL(const TSize& aSize) = 0;
376 Releases an input buffer back to the media device without using it. This method is mainly used as a
377 response to a ReleaseBuffers() callback.
379 @param aBuffer The buffer to release.
381 virtual void MmvbmReleaseBuffer(TVideoPicture* aBuffer) = 0;
384 /*****************************************************************************/
386 MMmfVideoWindowControl Custom Interface UID.
391 const TUid KUidMmfVideoWindowControl = { 0x10282646 };
394 Enables the client to control video position using a logical video window,
395 and specify the exact location of the picture within that window.
396 The logical video window may be partially or completely off-screen.
401 class MMmfVideoWindowControl
405 Horizontal alignment constants.
410 The picture is horizontally centered.
414 The picture is horizontally left-aligned.
418 The picture is horizontally right-aligned.
424 Vertical alignment constants.
429 The picture is vertically centered.
433 The picture is vertically top-aligned.
437 The picture is vertically bottom-aligned.
443 Sets the logical video window to use for positioning the video
444 picture on the screen. By default the logical video window is the same
445 as the display video window set with StartDirectScreenAccessL().
447 @param aWindow Logical window rectangle, relative to the device display.
449 virtual void MmvwcSetLogicalVideoWindow(const TRect& aWindow) = 0;
452 Sets the offset where the video picture will be located in the
453 logical video window. By default the picture is centered in the window
454 if its content and window sizes do not match.
456 This method and MmvwcSetContentAlignment() are mutually exclusive, and
457 only one of them should be used. Calling one will override the settings
460 If an error occurs, this function leaves with any of the system
461 wide error codes. Common error codes are listed below.
463 @param aOffset Offset, the position of the upper left hand corner of the
464 picture relative to the upper left hand corner of the
465 logical window. The picture must be fully contained within the
468 @leave KErrArgument The picture is not fully contained within the window.
470 virtual void MmvwcSetContentOffsetL(const TPoint& aOffset) = 0;
473 Sets video picture alignment within the logical video window.
474 By default the picture is centered in the window
475 if its content and window sizes do not match.
477 This method and MmvwcSetContentOffsetL() are mutually exclusive, and
478 only one of them should be used. Calling one will override the settings
481 @param aHorizAlign Horizontal alignment within the logical window
482 @param aVertAlign Vertical alignment within the logical window
484 virtual void MmvwcSetContentAlignment(const THorizAlign aHorizAlign, const TVertAlign aVertAlign) = 0;
487 /*****************************************************************************/
489 KUidMmfVideoResourceManagement Custom Interface UID.
494 const TUid KUidMmfVideoResourceManagement = { 0x1028264B };
497 Video resource observer interface, implemented by clients using the
498 MMmfVideoResourceHandler custom interface.
503 class MMmfVideoResourceObserver
507 Indicates that a media device has lost its resources. The client must
508 synchronously pause or stop processing before returning from this method
509 so that the media device can release its resources to the system. If
510 the client does not pause or stop, resource loss will be handled as a
513 If the client is holding any buffers allocated by the media
514 device, such as video decoder input or output buffers, it must
515 synchronously return them before returning from this
516 method. Additionally, in video playback use, the client must empty
517 any queued output pictures from DevVideoPlay by repeatedly calling
518 CMMFDevVideoPlay::NextPictureL() and
519 CMMFDevVideoPlay::ReturnPicture() until no more pictures are
522 The client may start again or resume after receiving a
523 MmvroResourcesRestored() callback.
525 @param aMediaDevice UID for the media device that lost resources. The
526 client can use this for example to determine whether
527 the decoder or the post-processor lost resources.
528 This is typically not required though since the client
529 must pause DevVideo entirely.
531 virtual void MmvroResourcesLost(TUid aMediaDevice) = 0;
534 Indicates that a media device has regained its resources after a
535 previous resource loss. The client can restart or resume processing.
536 This can be done either synchronously or asynchronously.
538 @param aMediaDevice UID for the media device that regained resources.
540 virtual void MmvroResourcesRestored(TUid aMediaDevice) = 0;
546 Video hardware resource handler custom interface.
548 Video decoder, encoder, pre or post-processor media devices can implement
549 this interface. Clients can use this interface to register for resource
550 management notifications and to set resource management priorities.
552 This custom interface is only intended for media devices that can save
553 their internal state as resources are lost, making resource loss recoverable.
554 As such it is not appropriate for all media devices.
556 By default resource loss is considered a fatal error. Clients can
557 use the notification callbacks to pause or stop processing when resources
558 are lost and restart or resume when resources are available again, thus
559 avoiding errors and providing a better user experience.
564 class MMmfVideoResourceHandler
568 Sets the video resource observer to use. The observer will receive
569 resource loss and restore callbacks. If no observer has been set,
570 resources losses will be handled as fatal errors.
572 @param aObserver The observer to use, NULL to remove observer.
574 virtual void MmvrhSetObserver(MMmfVideoResourceObserver* aObserver) = 0;
577 /*****************************************************************************/
579 KUidMmfVideoResourcePriority Custom Interface UID.
584 const TUid KUidMmfVideoResourcePriority = { 0x1028264C };
587 Video resource priority control custom interface.
589 Video decoder, encoder, pre or post-processor media devices can implement
590 this interface. Clients can use this interface to set resource reservation
591 priority for the media device. Typically this interface is used to lower
592 the priority for background tasks to ensure they do not remove resources
593 from foreground applications.
598 class MMmfVideoResourcePriority
602 Sets the priority the media device uses to reserve resources.
603 Media devices with higher priority may override requests from ones
604 with a lower priority. This method can be called at any point, but
605 implementations may ignore it after initialization. Therefore clients
606 should call this before calling Initialize().
608 The behaviour of the underlying resource manager and policy is
609 implementation-specific. Most implementations will limit high
610 priorities to clients that have certain capabilities
611 (for example, MultimediaDD) or specific Vendor IDs only.
612 All implementations should do some policing to ensure untrusted
613 applications cannot block the system by allocating all available
614 resources at a high priority.
616 @param aPriority Resource management priority. The values use the same
617 range as TMdaPriority.
619 virtual void MmvpSetResourcePriority(TInt aPriority) = 0;
622 /*****************************************************************************/
624 KUidMmfVideoPropertiesManagement Custom Interface UID.
629 const TUid KUidMmfVideoPropertiesManagement = { 0x10283231 };
632 Video property change observer. DevVideoPlay clients or media devices can
633 implement this observer and use the MMmfVideoPropertiesNotifier extension
634 to receive notifications when decoded video properties (such as picture
635 size and pixel aspect ratio) change.
640 class MMmfVideoPropertiesObserver
644 Decoded video properties updated. The media device implementing the
645 MMmfVideoPropertiesNotifier extension will call this method immediately
646 before outputting a picture with the updated properties.
648 When the extension is used between a decoder and a post-processor media
649 device, the post-processor can associate the changed properties with the
650 correct picture, since the next incoming picture after this call will
651 be the first updated one.
653 When the extension is used between a DevVideoPlay client and a
654 post-processor media device, the client can synchronously reconfigure
655 video display options using SetScaleOptionsL() and related methods. This
656 lets the client reconfigure the display for the correct picture.
658 @param aYuvFormat Updated YUV format parameters. The updated fields are
659 iAspectRatioDenom, iAspectRatioNum, and iCoefficients
660 @param aPictureSize Updated picture size. This size will be the true
661 picture display size, excluding any padding that
664 virtual void MmvpoUpdateVideoProperties(const TYuvFormat& aYuvFormat, const TSize& aPictureSize) = 0;
669 Video property notifier extension. DevVideoPlay decoders and post-processor
670 can implement this extension to provide notifications when decoded video
671 picture properties such as size or pixel aspect ratio change. The extension
672 is typically used to get size and pixel aspect ratio updates from a decoder
673 to a post-processor media device, and from a post-processor to the
679 class MMmfVideoPropertiesNotifier
683 Sets a new video properties observer. This method can be called at any
684 time after the media device has been instantiated.
686 @param aObserver New observer object.
688 virtual void MmvpnSetObserver(MMmfVideoPropertiesObserver* aObserver) = 0;
693 KUidMmfVideoH324AnnexKMode Custom Interface UID.
698 const TUid KUidMmfVideoH324AnnexKMode = { 0x102836C2 };
701 Video encoder H.324M Annex K mode extension. DevVideoRecord MPEG-4 and H.264
702 encoders can implement this extension to support using ITu-T H.324 Annex K
708 class MMmfVideoH324AnnexKMode
712 * Enables or disables encoder ITU-T H.324M Annex K mode. This method
713 * is only applicable for MPEG-4 and H.264 video.
715 * When the encoder is in Annex K mode, it will use the encoding
716 * parameters and bitstream headers defined in ITU-T H.324M Annex
717 * K. Enabling Annex K mode will reset all the specified settings
718 * apart from picture size and output format to the values
719 * specified in Annex K. This includes codec profile and level,
720 * maximum bit rate, and other encoding constraints.
722 * When Annex K mode is active, the client cannot change encoder settings
723 * that would conflict with the ones specified in Annex K. Attempts to do
724 * so will cause the corresponding setting methods to fail with
727 * Annex K mode can be deactivated by calling this method with a false
728 * parameter. This will remove restrictions on encoder settings.
730 * This method can only be called before the encoder is
731 * initialized. The client should set the input and output formats
732 * and picture size before calling this method.
734 * If an error occurs this method will fail with a system-wide error code.
735 * Typical error codes are listed below.
736 * Typically errors are only expected if the current output format or
737 * picture size do not meet Annex K constraints.
739 * @param aAnnexKMode ETrue to enable H.324M Annex K mode, EFalse to
742 * @pre The client has called SelectEncoderL(), SetOutputFormatL(), and
743 * SetInputFormatL(). This method can only be called before
746 * @leave KErrNotSupported Annex K mode cannot be supported with the
747 * current settings. Possible causes are incorrect
748 * output format (not MPEG-4 or H.264) or picture
751 virtual void MmvhakmSetH324MAnnexKModeL(TBool aAnnexKMode) = 0;
756 MMmfVideoClientThreadInfo interface UID.
760 const TUid KMmfUidDevVideoClientThreadInfoCustomInterface = {0x102834A9};
766 Custom interface providing support for setting the client thread info for the DevVideo.
768 class MMmfVideoClientThreadInfo
772 Set client thread info for the DevVideo.
774 @param aTid the client thread Id.
775 @return An error code indicating if the function call was successful.
777 virtual TInt MmvctSetClientThreadInfo(TThreadId aTid) = 0;