diff -r 000000000000 -r 15bf7259bb7c uiaccelerator_plat/alf_visual_api/inc/alf/alfutil.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uiaccelerator_plat/alf_visual_api/inc/alf/alfutil.h Tue Feb 02 07:56:43 2010 +0200 @@ -0,0 +1,393 @@ +/* +* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "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: +* +* Description: Misc. utilities +* +*/ + + + +#ifndef C_ALFUTIL_H +#define C_ALFUTIL_H + + +#include +#include +#include +#include + +/* Forward declarations. */ +struct TAlfRealPoint; + + +/** + * AlfUtil is a collection of utility routines for Alfred.dll. + * Many of the utility routines are mathematical operations such as + * the calculation of a vector cross product or linear interpolation between two + * values. + * + * AlfUtil contains only static member functions. It cannot be instantiated. + */ +NONSHARABLE_CLASS(AlfUtil) + { +public: + + /** @beginAPI */ + + /** + * Calculates the smallest power-of-two that is equal to or greater than + * a value (rounds value up to the nearest power-of-two). + * + * @param aValue Integer value. + * + * @return Smallest power-of-two that is equal to or greater than + * aValue. + * + * @see Power2RoundDown() for down-rounding equivalent. + */ + IMPORT_C static TInt Power2(TInt aValue); + + /** + * Calculates the largest power-of-two that is equal to or smaller than + * a value (rounds the value down to nearest power-of-two). + * + * @param aValue Integer value. + * + * @return Smallest power-of-two that is equal to or greater than + * aValue. + */ + IMPORT_C static TInt Power2RoundDown(TInt aValue); + + /** + * Interpolates between two values. Calculates a linear interpolation + * between a minimum and maximum value. + * + * @param aPos Position. 0.0 corresponds to the minimum value, 1.0 + * corresponds to the maximum value. Positions outside this + * range are allowed, which results in extrapolation. + * @param aMin Minimum value. + * @param aMax Maximum value. + * + * @return Interpolated value. + */ + IMPORT_C static TReal32 Interpolate(TReal32 aPos, TReal32 aMin, TReal32 aMax) __SOFTFP; + + /** + * Wraps a value to a range. + * + * @param aValue Reference to the value to wrap. Will be modified. + * @param aLow Range minimum. If aValue is equal to aLow, it will remain + * at aLow. + * @param aHigh Range maximum. If aValue is equal to aHigh, it will be + * wrapped to aLow. + */ + IMPORT_C static void WrapValue(TReal32& aValue, TReal32 aLow, TReal32 aHigh) __SOFTFP; + + /** + * Generates a random integer. + * + * @param aMin Minimum possible value. + * @param aMax Maximum possible value. + * + * @return Random integer between the minimum and maximum values, + * inclusive. + */ + IMPORT_C static TInt RandomInt(TInt aMin, TInt aMax); + + /** + * Generates a random real number. + * + * @param aMin Minimum possible value. + * @param aMax Maximum possible value. + * + * @return Random real number between the minimum and maximum values, + * inclusive. + */ + IMPORT_C static TReal32 RandomReal(TReal32 aMin, TReal32 aMax) __SOFTFP; + + /** + * Approximates the length of a 2D vector. This is done without + * calculating a square root. + * + * @param aVector 2D vector as a point. The X and Y components are + * interpreted as deltas. + * + * @return Approximate length of the vector. + */ + IMPORT_C static TReal32 QuickLength(TAlfRealPoint& aVector) __SOFTFP; + + /** + * Approximates the length of a 2D vector. This is done without + * calculating a square root. + * + * @param aDx X delta of the vector. + * @param aDy Y delta of the vector. + * + * @return Approximate length of the vector. + */ + IMPORT_C static TReal32 QuickLength(TReal32 aDx, TReal32 aDy) __SOFTFP; + + /** + * Normalizes a vector so that its length will be approximately 1.0. + * This is done without calculating a square root. + * + * @param aVector 2D vector to be normalized as a point. The X and Y + * components are interpreted as deltas. Will be modified. + */ + IMPORT_C static void QuickNormalize(TAlfRealPoint& aVector); + + /** + * Normalizes a vector so that its length will be approximately 1.0. + * This is done without calculating a square root. + * + * @param aVector 3D vector to be normalized as a point (X, Y, Z components + * as an array of TReal32). Will be modified. + */ + IMPORT_C static void QuickNormalize(TReal32 aVector[3]) __SOFTFP; + + /** + * Calculates a cross product of 3D vectors. aProduct = aA x aB. + * + * @param aA 3D vector. + * @param aB 3D vector. + * @param aProduct 3D vector where the cross product is returned. + */ + IMPORT_C static void CrossProduct(const TReal32 aA[3], const TReal32 aB[3], TReal32 aProduct[3]) __SOFTFP; + + /** + * Calculates a normal vector for a plane defined by three points. + * + * @param aPoints Array of three 3D vectors. The first index is the number + * of the vector, the second index is the vector component + * (x, y, z). + * @param aNormal Resulting normal vector. + */ + IMPORT_C static void NormalFromPoints(const TReal32 aPoints[3][3], TReal32 aNormal[3]) __SOFTFP; + + /** + * Calculates a matrix that projects 3D points onto a plane. The name + * ShadowMatrix comes from the intended usage: when used as a modelview + * matrix, this matrix will flatten a 3D mesh onto a projected shadow. + * + * @param aPlanePoint Point on the plane onto which the shadow is casted. + * @param aPlaneNormal Normal of the plane onto which the shadow is casted. + * @param aLightPos Position of the light source. + * @param aDestMat Resulting matrix. + */ + IMPORT_C static void ShadowMatrix(const TReal32 aPlanePoint[3], + const TReal32 aPlaneNormal[3], + const TReal32 aLightPos[4], + TReal32 aDestMat[16]) __SOFTFP; + + /** + * Determines the amount of free memory in the system. + * + * @param aTotalMemory If not NULL, the total amount of memory is + * returned here. + * + * @return Bytes of free memory. + */ + IMPORT_C static TUint FreeMemory(TUint* aTotalMemory = 0); + + /** + * Determines the native resolution of the device's screen. + * + * @return Screen size in pixels. + */ + IMPORT_C static TSize ScreenSize(); + + /** + * Finds the font that is the closest match to a font specification. + * Note that the returned font instance must be released with + * AlfUtil::ReleaseFont(). Deleting the returned font instance is not allowed. + * + * @param aFontSpec Font specification. + * + * @return Font instance. Must be released with a call to AlfUtil::ReleaseFont() + * when no longer needed. + */ + IMPORT_C static CFont* NearestFontInTwipsL(const TFontSpec& aFontSpec); + + /** + * Releases a font that was returned by NearestFontInTwipsL(). Must be + * called when the font is no longer needed. + * + * @param aFont Font returned by a previous allocation by AlfUtil. + */ + IMPORT_C static void ReleaseFont(CFont* aFont); + + /** + * Calculates a display size dependent length unit. This can be used for + * layout calculations that should be independent of the display size. + * For example, this could be the distance at which a shadow is drawn + * behind text strings (assuming the font size also depends on display + * size). + * + * @return Length unit. + */ + IMPORT_C static TReal32 LengthUnit() __SOFTFP; + + /** + * Approximates the lightness of a color. The returned value is in range + * 0...1, where 0.0 means the equivalent of black and 1.0 means the + * equivalent of white. This is similar to the Value component in the HSV + * color model (but not exactly the same). + * + * @param aColor Color whose lightness is to be evaluated. + * + * @return Lightness value. + */ + IMPORT_C static TReal32 ColorLightness(const TRgb& aColor) __SOFTFP; + + /** + * Resamples given FBS bitmap to new size (converting + * color modes along the way..) + * @param aSrcBitmap Source bitmap to resample. + * @param aScaledBitmap Output bitmap. The original size of + * this CFbsBitmap defines the size of the downscaled bitmap. + */ + IMPORT_C static void ScaleFbsBitmapL(const CFbsBitmap & aSrcBitmap, + CFbsBitmap & aScaledBitmap); + + /** + * Converts separate mask and color bitmaps into single + * EColor16MA (24bpp colour plus 8bpp alpha) bitmap. + * @param aBitmap Source color channel bitmap. + * @param aMaskBitmap The source alpha mask bitmap. Use either a black and + * white (binary) mask bitmap, or if aMaskBitmap's display mode is EGray256, + * alpha blending is used. Use of any other mode may result in unpredictable + * results. + * @param aCombinedBitmap Bitmap that will to contain the target + * EColor16MA bitmap with color information from aBitmap and alpha information + * from aMaskBitmap. NOTE: Must have color mode EColor16MA! + */ + IMPORT_C static void CombineMaskFbsBitmapL(const CFbsBitmap & aSrcBitmap, + const CFbsBitmap & aSrcMaskBitmap, + CFbsBitmap & aCombinedBitmap); + + /** + * Crops an area of FBS bitmap to new image. The size of the + * copped bitmap defines the size of the area to crop. + */ + IMPORT_C static void CropFbsBitmapL(const CFbsBitmap & aSrcBitmap, + CFbsBitmap & aCroppedBitmap, + TPoint aCropPosition); + + /** + * Resamples given unsigned byte image data to new size. Uses box + * filtering. Can be used to downscale too large textures, for example. + * + * @param aComponents Number of image components (color channels) in the + * source image. Use 3 with RGB image and 4 with RGBA. The destination will + * have the same amount of color channels after this operation. + * @param aSrcSize Size (width and height) of the original image (aSrcBuffer), + * in number of pixels (width) or rows (height). + * @param aSrcBuffer Pointer to the source image data. + * @param aDestSize Size (width and height) of the new scaled image, + * (aDestBuffer) in number of pixels (width) or rows (height). + * @param aDestBuffer Output parameter: Pointer where new scaled image + * data will be stored. You must remember to allocate the space for the + * buffer before calling this method. + */ + IMPORT_C static void ScaleImage(TInt aComponents, + const TSize& aSrcSize, + const TUint8* aSrcBuffer, + const TSize& aDestSize, + TUint8* aDestBuffer); + + /** + * Crops given unsigned byte image data. Can be used to split + * large images to smaller sections. + * + * @param aComponents Number of image components (color channels) in the + * source image. Use 3 with RGB image and 4 with RGBA. The destination will + * have the same amount of color channels after this operation. + * @param aSrcBufferSize Size (width and height) of the original image (aSrcBuffer), + * in number of pixels (width) or rows (height). + * @param aSrcBuffer Pointer to the source image data. + * @param aCropOffset Cropping offset in the source image. Location of the + * top-left corner of the cropped area, in pixels. + * @param aCroppedSize Size of the cropped area. Is also the size of the + * image in aDestBuffer. Width and height in pixels. + * @param aDestBuffer Output parameter: Pointer where the cropped image + * data will be stored. You must remember to allocate the space for the + * buffer before calling this method. + */ + IMPORT_C static void CropImage(TInt aComponents, + const TSize& aSrcBufferSize, + const TUint8* aSrcBuffer, + const TPoint& aCropOffset, + const TSize& aCroppedSize, + TUint8* aDestBuffer); + + + /** + * Checks if aTag is included in aTagsColonSeparated. Tags are case-sensitive. + * + * @param aTagsColonSeparated One or more tags separated by colons (:). + * For example: "hello:world:tag3". + * @param aTag Tag to look for. For example: "world". + * + * @return ETrue, if the tag was found in the colon-separated + * tags descriptor. EFalse otherwise. + * + * @see CAlfVisual::FindTag() + */ + IMPORT_C static TBool TagMatches(const TDesC8& aTagsColonSeparated, const TDesC8& aTag); + + /** + * Converts a bitmap to specified display mode. + * This method converts a bitmap in any display mode to specified display mode. + * Method creates a new bitmap, leaves it in cleanup stack and returns it. + * + * @param aBitmap The bitmap to be converted. + * @param aDisplaymode The target display mode to convert the bitmap into. + * @return Newly created conversion of the source bitmap. + */ + IMPORT_C static CFbsBitmap* ConvertBitmapToDisplayModeLC( const CFbsBitmap& aBitmap, const TDisplayMode& aDisplaymode ); + + + /** + * @deprecated Always returns KAknsIIDNone<\b> + * + * Retrieves the TAknsItemID corresponding to the Textual skin identifier + * + * @param aEnv Alf Environment variable + * @param aSkinId The textual identifier for which corresponding TAknsItemID is + * required + * + * @return TAknsItemID object corresponding to aSkinId + */ + IMPORT_C static TAknsItemID ThemeItemIdL(CAlfEnv& aEnv, const TDesC& aSkinId ); + + /** @endAPI */ + + /** + * Asserts if the given condition is false. + */ + static void Assert(TBool aCondition); + + /** + * Rounds a float (TReal32) correctly into an integer (TInt). Takes care of both negative + * and positive real number. + * + * @param aVal The value to be rounded to the closest integer. + * @return Rounded integer. + */ + static TInt RoundFloatToInt(TReal32 aVal); + + }; + + + +#endif // C_ALFUTIL_H