/*
* Copyright (c) 2010 Ixonos Plc.
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the "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:
* Ixonos Plc
*
* Description:
*
*/
#ifndef __VEDVIDEOCLIPGENERATOR_H__
#define __VEDVIDEOCLIPGENERATOR_H__
#include <e32base.h>
#include <fbs.h>
#include "VedVideoClipInfo.h"
class CVedMovie;
class CVedVideoClip;
class CVedVideoClipGenerator;
/**
* Observer for notifying that video clip frame has been completed.
*
* @see CVedVideoClipGenerator
*/
class MVedVideoClipGeneratorFrameObserver
{
public:
/**
* Called to notify that a video clip frame has been completed.
*
* @param aGenerator video clip generator
* @param aError <code>KErrNone</code> if frame was
* completed successfully; one of the system wide
* error codes if generating frame failed
* @param aFrame pointer to frame if it was completed successfully;
* <code>NULL</code> if generating frame failed
*/
virtual void NotifyVideoClipGeneratorFrameCompleted(CVedVideoClipGenerator& aGenerator,
TInt aError,
CFbsBitmap* aFrame) = 0;
};
/**
* Abstract base class for video clip frame generators. Frame generators
* can be used to create video clips from bitmaps generated by the application
* (for example, by drawing with GDI).
*/
class CVedVideoClipGenerator : public CBase
{
public:
/**
* Destructor.
*/
IMPORT_C virtual ~CVedVideoClipGenerator();
/**
* Returns whether this generator has been inserted to a movie
* or not.
*
* @return <code>ETrue</code>, if this generator has been
* inserted; <code>EFalse</code>, otherwise
*/
IMPORT_C TBool IsInserted() const;
/**
* Returns the movie this generator is associated with.
* Panics with <code>EVideoClipGeneratorNotInserted</code>
* if this generator has not been inserted to a movie yet.
*
* @return movie
*/
IMPORT_C CVedMovie* Movie() const;
/**
* Returns the index of the video clip this generator is
* associated with.Panics with <code>EVideoClipGeneratorNotInserted</code>
* if this generator has not been inserted to a movie yet.
*
* @return video clip index
*/
IMPORT_C TInt VideoClipIndex() const;
/**
* Returns whether this generator is owned by the video clip
* it is associated with (i.e., whether the video clip is responsible
* for deleting this generator). Panics with
* <code>EVideoClipGeneratorNotInserted</code> if this generator
* has not been inserted to a movie yet.
*
* @return <code>ETrue</code>, if this generator is owned by
* the video clip; <code>EFalse</code>, otherwise
*/
IMPORT_C TBool IsOwnedByVideoClip() const;
/**
* Returns the uid of the frame generator. The use of the uid is
* entirely application specific. It can be used for example to
* identify the frame generator type. The uid is not used in
* any way by the video editor engine.
*
* @return uid of the frame generator
*/
virtual TUid Uid() const = 0;
/**
* Returns a descriptive name for the clip.
*
* @return descriptive name of the clip
*/
virtual TPtrC DescriptiveName() const = 0;
/**
* Returns the duration of the clip in microseconds.
*
* @return duration of the clip
*/
virtual TTimeIntervalMicroSeconds Duration() const = 0;
/* Video frame property methods. */
/**
* Returns the number of video frames in this clip. Panics if the
* clip is not ready.
*
* @return number of video frames in this clip
*/
virtual TInt VideoFrameCount() const = 0;
/**
* Returns the start time of the video frame at the specified index.
* Panics if the index is illegal or if the clip is not ready.
*
* @param aIndex index
*
* @return start time of the video frame at the specified index in microseconds
*/
virtual TTimeIntervalMicroSeconds VideoFrameStartTime(TInt aIndex) const = 0;
/**
* Returns the end time of the video frame at the specified index.
* Panics if the index is illegal or the clip is not ready.
*
* @param aIndex index
*
* @return end time of the video frame at the specified index in microseconds
*/
virtual TTimeIntervalMicroSeconds VideoFrameEndTime(TInt aIndex) const = 0;
/**
* Returns the duration of the video frame at the specified index.
* Panics if the index is illegal or the clip is not ready.
*
* @param aIndex index
*
* @return duration of the video frame at the specified index in microseconds
*/
virtual TTimeIntervalMicroSeconds VideoFrameDuration(TInt aIndex) const = 0;
/**
* Returns the complexity factor of the first video frame. The complexity factor
* should be in the range between 0 to 1000. 0 means no variation at all (a
* blank frame), 1000 means a highly complex frame.
*
* @see CalculateFrameComplexityFactor
*
* @return complexity factor, range 0...1000
*/
virtual TInt VideoFirstFrameComplexityFactor() const = 0;
/**
* Returns the difference factor of the video frame at the specified
* index. The difference factor describes how different the frame is
* from the previous frame. The difference factor should be in the range between
* 0 to 1000 (0 means that the frame is identical to the previous one, 1000
* means that the frame is completely different from the previous one.)
* Panics if the index is illegal or the clip is not yet ready.
*
* @param aIndex index (starting from 1)
*
* @return difference factor, range 0...1000
*/
virtual TInt VideoFrameDifferenceFactor(TInt aIndex) const = 0;
/**
* Returns the video frame index at the specified time. Panics if info is not yet
* ready for reading or the time is illegal.
*
* @param aTime time
*
* @return video frame index at the specified time
*/
virtual TInt GetVideoFrameIndex(TTimeIntervalMicroSeconds aTime) const = 0;
/* Frame methods. */
/**
* Generates a bitmap of the given frame. The frame bitmap is scaled
* to the specified resolution and converted to the specified display
* mode. This method is asynchronous. The frame is generated in the
* background and the observer is notified when the frame is complete.
* This method panics if the resolution is illegal.
*
* Possible leave codes:
* - <code>KErrNoMemory</code> if memory allocation fails
* - <code>KErrNotSupported</code>, if the specified combination of
* parameters is not supported
*
* @param aObserver observer to be notified when the frame is completed
* @param aIndex index of frame, or KFrameIndexBestThumb to look for
* the most suitable thumbnail frame.
* @param aResolution resolution of the desired frame bitmap, or
* <code>NULL</code> if the frame should be
* in the original resolution
* @param aDisplayMode desired display mode; or <code>ENone</code> if
* any display mode is acceptable
* @param aEnhance apply image enhancement algorithms to improve
* frame quality; note that this may considerably
* increase the processing time needed to prepare
* the frame
* @param aPriority priority of the frame generation
*/
virtual void GetFrameL(MVedVideoClipGeneratorFrameObserver& aObserver,
TInt aIndex = KFrameIndexBestThumb,
TSize* const aResolution = 0,
TDisplayMode aDisplayMode = ENone,
TBool aEnhance = EFalse,
TInt aPriority = CActive::EPriorityIdle) = 0;
/**
* Cancels frame generation. If no frame is currently being
* generated, the function does nothing.
*/
virtual void CancelFrame() = 0;
protected: // constructors and methods
/**
* Constructor.
*/
IMPORT_C CVedVideoClipGenerator();
/**
* Reports to the base class that the duration of the generated clip has
* changed. This method should <emph>always</emph> be called when the
* settings of the generated clip change so that the duration of the
* clip is affected.
*/
IMPORT_C void ReportDurationChanged() const;
/**
* Reports to the base class that some settings of the generated clip have
* changed but the duration of the clip has remained the same.
* This method should <emph>always</emph> be called when any settings
* of the generated clip change but the duration of the clip is not affected.
*/
IMPORT_C void ReportSettingsChanged() const;
/**
* Reports to the base class that descriptive name of the generated
* clip has changed. This method should <emph>always</emph> be called
* when the descriptive name of the generated clip has changed but no
* other changes have occurred.
*/
IMPORT_C void ReportDescriptiveNameChanged() const;
/**
* Calculates the complexity of a frame. This method is meant for calculating
* frame complexity factors returned by <code>VideoFirstFrameComplexityFactor</code>
* method.
*
* @see VideoFirstFrameComplexityFactor
*
* @param aFrame frame to analyze
*
* @return complexity factor
*/
IMPORT_C TInt CalculateFrameComplexityFactor(CFbsBitmap* aFrame) const;
private: // methods
/**
* Sets the video clip this generator is associated with and whether
* the clip owns this generator or not. Note that these properties can
* be set only once during the lifetime of a generator when the
* generator is inserted to a movie. Panics with
* <code>EVideoClipGeneratorAlreadyInserted</code> if the video clip
* has already been set.
*
* @param aVideoClip video clip
* @param aIsOwnedByVideoClip <code>ETrue</code>, if the clip is responsible
* for deleting this generator; <code>EFalse</code>,
* otherwise
*/
void SetVideoClip(CVedVideoClip& aVideoClip, TBool aIsOwnedByVideoClip);
private:
// Member variables
CVedVideoClip* iVideoClip;
TBool iIsOwnedByVideoClip;
TInt iMaximumFramerate;
friend class CVedMovieAddClipOperation;
friend class CVideoEditorTest;
};
#endif // __VEDVIDEOCLIPGENERATOR_H__