1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/icl/imageconversionextensionintf.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,295 @@
1.4 +// Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef IMAGECONVERSIONEXTENSIONINTF_H
1.20 +#define IMAGECONVERSIONEXTENSIONINTF_H
1.21 +
1.22 +#include <icl/imageconversionextension.h>
1.23 +
1.24 +class CImageFrame;
1.25 +class CFrameImageData;
1.26 +
1.27 +/**
1.28 +@file
1.29 +@publishedAll
1.30 +@released
1.31 +*/
1.32 +
1.33 +/**
1.34 + Image Conversion Library extensions. When applied together there is an implicit order for operations:
1.35 + 1. Crop or clip.
1.36 + 2. Scale
1.37 + 3. Rotate / flip.
1.38 +
1.39 +In order to support an extension the codec plugin must implement the interface and return this interface
1.40 +through a call to CImageDecoderPlugin::GetExtensionL.
1.41 +*/
1.42 +
1.43 +/**
1.44 +Extension base class
1.45 +*/
1.46 +class MImageConvExtension
1.47 + {
1.48 +public:
1.49 + /**
1.50 + Uid of extension interface.
1.51 + */
1.52 + virtual TUid Uid() const = 0;
1.53 +
1.54 + /**
1.55 + Increment the reference count.
1.56 + */
1.57 + virtual void IncrementRef() = 0;
1.58 +
1.59 + /**
1.60 + Called when the client has finished with this interface allowing the codec to clean up.
1.61 + */
1.62 + virtual void Release() = 0;
1.63 + };
1.64 +
1.65 +/**
1.66 +Operation extension for Image Conversion Library. Allows rotation and mirror/flip.
1.67 +*/
1.68 +class MImageConvOperation : public MImageConvExtension
1.69 + {
1.70 +public:
1.71 + /**
1.72 + Capabilities of the code plugin.
1.73 +
1.74 + @return Bitmask combination of TOperation. Bit is set if decoder plugin supports the operation.
1.75 + */
1.76 + virtual TUint Capabilities() const = 0;
1.77 +
1.78 + /**
1.79 + Set up an operation be applied to the source. May be called more than once
1.80 + to set up a stack of operations, but it is not possible to add more than one
1.81 + operation in a single call.
1.82 +
1.83 + @param aOperation An operation to be added to the current operation stack.
1.84 +
1.85 + @leave if more than one TOperation enum is passed for each individual call
1.86 + */
1.87 + virtual void AddOperationL(TImageConvOperation::TOperation aOperation) = 0;
1.88 +
1.89 + /**
1.90 + Remove all operations previously set.
1.91 + */
1.92 + virtual void ClearOperationStack() = 0;
1.93 + };
1.94 +
1.95 +/**
1.96 +Scaling extension for Image Conversion Library
1.97 +*/
1.98 +class MImageConvScaler : public MImageConvExtension
1.99 + {
1.100 +public:
1.101 + /**
1.102 + Gets the scaling capabilities.
1.103 +
1.104 + @param aCaps Returns scaling capabilities of the codec plugin.
1.105 + */
1.106 + virtual void GetCapabilities(TScalerCaps& aCaps) const = 0;
1.107 +
1.108 + /**
1.109 + Request scaling to the desired size using the quality specified and specifying if the aspect ratio is to
1.110 + be preserved.
1.111 + @param aDesiredSize Proposed size of the scaled image.
1.112 + @param aQuality Desired quality of the image. Allows codec to lower quality targets to
1.113 + improve performance.
1.114 + @param aLockAspectRatio Set to ETrue if the aspect ratio of the original image is to be preserved.
1.115 + @leave KErrNotSupported if an invalid size is passed.
1.116 + @leave KErrNotSupported if aLockAspectRatio is EFalse and codec only supports preservation of aspect ratio.
1.117 + */
1.118 + virtual void SetScalingL(const TSize& aDesiredSize, TImageConvScaler::TScalerQuality aQuality, TBool aLockAspectRatio) = 0;
1.119 +
1.120 + /**
1.121 + Define the scaling to be applied to the image according to the given coefficient at the requested quality.
1.122 +
1.123 + @param aScalingCoeff Scale to apply to the source. 2 means twice the original size, -2 half the size.
1.124 + Do not confuse this with ReductionFactor where 2 indicates 1/2 size.
1.125 + @param aScalingQuality Desired quality of the image. Allows codec to lower quality targets to
1.126 + improve performance.
1.127 + @leave KErrNotSupported if codec cannot perform the requested scale.
1.128 + */
1.129 + virtual void SetScalingL(TInt aScalingCoeff, TImageConvScaler::TScalerQuality aScalingQuality) = 0;
1.130 + };
1.131 +
1.132 +/**
1.133 +Block Streaming extension for decoder plugins.
1.134 +*/
1.135 +class MImageConvStreamedDecode : public MImageConvExtension
1.136 + {
1.137 +public:
1.138 + /**
1.139 + Returns a list of supported formats and the optimal format to be used. @see imageframeconst.h
1.140 + for a list of format uids.
1.141 + @param aFormats Returns an array of format uids
1.142 + @param aOptimalFormat The 'best' uid to use.
1.143 + */
1.144 + virtual void GetSupportedFormatsL(RArray<TUid>& aFormats, TUid& aOptimalFormat) const = 0;
1.145 +
1.146 + /**
1.147 + Returns the capabilities of the codec plugin for a specific format.
1.148 + @param aFormat The format.
1.149 + @param aFrameNumber frame to stream
1.150 + @param aCaps The capabilities for the format given.
1.151 + */
1.152 + virtual void GetCapabilities(TUid aFormat, TInt aFrameNumber, TDecodeStreamCaps& aCaps) const = 0;
1.153 +
1.154 + /**
1.155 + Get the size of the memory buffer to hold the returned data.
1.156 +
1.157 + @param aFormat the required format
1.158 + @param aBlockSizeInPixels size of a single block to be returned
1.159 + @param aNumBlocks the number of blocks of size TDecodeStreamCaps::MinBlockSizeInPixels() to be returned by one request
1.160 + @return The memory buffer size in bytes to hold the requested blocks.
1.161 + */
1.162 + virtual TInt GetBufferSize(TUid aFormat, TSize& aBlockSizeInPixels, TInt aNumBlocks) const = 0;
1.163 +
1.164 + /**
1.165 + Initialise the stream.
1.166 + @param aFormat the format to use
1.167 + @param aFrameNumber frame to stream
1.168 + @param aNavigation indication to stream of the way that the stream will be navigated. Allows
1.169 + codec to optimise it's behaviour.
1.170 +
1.171 + @note TO DO Do we need to specify where the source is held e.g. in memory, on flash card etc?
1.172 +
1.173 + @note must call InitFrameL before GetBlocks or GetNextBlocks. Failure to do so completes request with
1.174 + KErrNotReady
1.175 + */
1.176 + virtual void InitFrameL(TUid aFormat, TInt aFrameNumber, TDecodeStreamCaps::TNavigation aNavigation) = 0;
1.177 +
1.178 + /**
1.179 + Start asynchronous call to return random blocks from the stream
1.180 +
1.181 + @param aStatus request status
1.182 + @param aFrame An image frame wrapper a memory buffer to hold the returned block(s) of
1.183 + pixel data. This can be 'uninitialised' or given specific format which must match that
1.184 + specified in the InitFrameL call.
1.185 + @param aSeqPosition block number starting at 0 ...
1.186 + @param aNumBlocksToGet number of blocks requested
1.187 + @param aNumBlocksRead number of blocks which will be returned when the request completes
1.188 +
1.189 + @note use CImageDecoder::Cancel() to cancel this request.
1.190 + */
1.191 + virtual void GetBlocks(TRequestStatus* aStatus, CImageFrame* aFrame, TInt aSeqPosition, TInt aNumBlocksToGet, TInt* aNumBlocksRead) = 0;
1.192 +
1.193 + /**
1.194 + Start asynchronous call to return blocks sequentially from the stream. Blocks are returned
1.195 + from the first block until the last in the stream.
1.196 +
1.197 + @param aStatus request status
1.198 + @param aFrame An image frame wrapper a memory buffer to hold the returned block(s) of
1.199 + pixel data. This can be 'uninitialised' or given specific format which must match that
1.200 + specified in the InitFrameL call.
1.201 + @param aNumBlocksToGet number of blocks requested
1.202 + @param aNumBlocksRead number of blocks which will be returned when the request completes
1.203 +
1.204 + @note use CImageDecoder::Cancel() to cancel this request.
1.205 + */
1.206 + virtual void GetNextBlocks(TRequestStatus* aStatus, CImageFrame* aFrame, TInt aNumBlocksToGet, TInt* aNumBlocksRead, TBool* aHaveMoreBlocks) = 0;
1.207 + };
1.208 +
1.209 +/**
1.210 +Block Streaming extension for encoder plugins.
1.211 +*/
1.212 +class MImageConvStreamedEncode : public MImageConvExtension
1.213 + {
1.214 +public:
1.215 + /**
1.216 + Returns a list of supported formats and the optimal format to be used. @see imageframeconst.h
1.217 + for a list of format uids.
1.218 + @param aFormats Returns an array of format uids
1.219 + @param aOptimalFormat The 'best' uid to use.
1.220 + */
1.221 + virtual void GetSupportedFormatsL(RArray<TUid>& aFormats, TUid& aOptimalFormat) const = 0;
1.222 +
1.223 + /**
1.224 + Returns the capabilities of the codec plugin for a specific format.
1.225 + @param aFormat The format.
1.226 + @param aCaps The capabilities for the format given.
1.227 + */
1.228 + virtual void GetCapabilities(TUid aFormat, TEncodeStreamCaps& aCaps) const = 0;
1.229 +
1.230 + /**
1.231 + Initialise the stream.
1.232 + @param aFormat the format to use
1.233 + @param aFrameNumber frame to stream
1.234 + @param aFrameSizeInPixels Size of this frame in pixels
1.235 + @param aBlockSizeInPixels Size of block to be added / appended. ??? do we want to support multiple blocks being added
1.236 + in which case InitFrameL needs an extra parameter
1.237 + @param aNavigation indication to stream of the way that the stream will be navigated. Allows
1.238 + codec to optimise it's behaviour.
1.239 + @param aFrameImageData The frame image data. Optional.
1.240 + There exists format-specific image data variants that are used by
1.241 + encoders to obtain image specific data. This behaviour is invoked by specifying
1.242 + aFrameImageData. Otherwise, if set to NULL, encoder specific defaults are invoked. @see TJpegImageData
1.243 +
1.244 + @note TO DO Do we need to specify where the destination is held e.g. in memory, on flash card etc?
1.245 +
1.246 + @note must call InitFrameL before AppendBlocks or AddBlocks. Failure to do so completes request with
1.247 + KErrNotReady
1.248 +
1.249 + @note can either specify format through aFormat or aImageFrameData. Conflicts should leave with KErrArgument.
1.250 + */
1.251 + virtual void InitFrameL(TUid aFormat, TInt aFrameNumber, const TSize& aFrameSizeInPixels, const TSize& aBlockSizeInPixels, TEncodeStreamCaps::TNavigation aNavigation, const CFrameImageData* aFrameImageData) = 0;
1.252 +
1.253 + /** Append blocks to the stream.
1.254 + @param aStatus request status
1.255 + @param aBlocks wraps a memory buffer containing the pixel data to be added to the stream
1.256 + @param aNumBlocksToAdd number of blocks of size TEncodeStreamCaps::MinBlockSizeInPixels to add to the stream
1.257 + */
1.258 + virtual void AppendBlocks(TRequestStatus* aStatus, const CImageFrame& aBlocks, TInt aNumBlocksToAdd) = 0 ;
1.259 +
1.260 + /** Add blocks to the stream at a random position.
1.261 + @param aStatus request status
1.262 + @param aBlocks wraps a memory buffer containing the pixel data to be added to the stream
1.263 + @param aSeqPosition position of block in stream starting at 0
1.264 + */
1.265 + virtual void AddBlocks(TRequestStatus* aStatus, const CImageFrame& aBlocks, const TInt& aSeqPosition) = 0;
1.266 +
1.267 + /** Signal completion of writing the stream
1.268 + @param aStatus request status
1.269 + */
1.270 + virtual void Complete(TRequestStatus* aStatus) = 0;
1.271 +private:
1.272 + TInt iReserved; // future proof
1.273 + };
1.274 +
1.275 +
1.276 +/**
1.277 +Extension for Prepare (analyse image in advance of conversion)
1.278 +*/
1.279 +class MImageConvPrepare : public MImageConvExtension
1.280 + {
1.281 +public:
1.282 + /**
1.283 + Call to allow analysis of image prior to calling Convert.
1.284 +
1.285 + @param aStatus
1.286 + Request status. On completion this contains an error code. This is KErrNone if the frame
1.287 + was analyzed successfully, KErrNotSupported if the codec does not support analysis, or a
1.288 + system-wide error code.
1.289 + */
1.290 + virtual void Prepare(TRequestStatus* aStatus) = 0;
1.291 +
1.292 +private:
1.293 + TInt iReserved; // future proof
1.294 + };
1.295 +
1.296 +
1.297 +
1.298 +#endif // IMAGECONVERSIONEXTENSIONINF_H