/*

* 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 <e32base.h>

#include <gdi.h>

#include <AknsItemID.h>

#include <alf/alfenv.h>

/* 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

     *          <code>aValue</code>.

     *

     * @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

     *          <code>aValue</code>.

     */

    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  <code>ETrue</code>, if the tag was found in the colon-separated

     *          tags descriptor. <code>EFalse</code> 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 <b>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