1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Misc. utilities

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef C_ALFUTIL_H

    21 #define C_ALFUTIL_H

    22 

    23 

    24 #include <e32base.h>

    25 #include <gdi.h>

    26 #include <AknsItemID.h>

    27 #include <alf/alfenv.h>

    28 

    29 /* Forward declarations. */

    30 struct TAlfRealPoint;

    31 

    32 

    33 /**

    34  * AlfUtil is a collection of utility routines for Alfred.dll.

    35  * Many of the utility routines are mathematical operations such as

    36  * the calculation of a vector cross product or linear interpolation between two

    37  * values.

    38  *

    39  * AlfUtil contains only static member functions. It cannot be instantiated.

    40  */

    41 NONSHARABLE_CLASS(AlfUtil)

    42     {

    43 public:

    44 

    45     /** @beginAPI */

    46 

    47     /**

    48      * Calculates the smallest power-of-two that is equal to or greater than

    49      * a value (rounds value up to the nearest power-of-two).

    50      *

    51      * @param aValue Integer value.

    52      *

    53      * @return  Smallest power-of-two that is equal to or greater than

    54      *          <code>aValue</code>.

    55      *

    56      * @see Power2RoundDown() for down-rounding equivalent.

    57      */

    58     IMPORT_C static TInt Power2(TInt aValue);

    59 

    60     /**

    61      * Calculates the largest power-of-two that is equal to or smaller than

    62      * a value (rounds the value down to nearest power-of-two).

    63      *

    64      * @param aValue  Integer value.

    65      *

    66      * @return  Smallest power-of-two that is equal to or greater than

    67      *          <code>aValue</code>.

    68      */

    69     IMPORT_C static TInt Power2RoundDown(TInt aValue);

    70 

    71     /**

    72      * Interpolates between two values. Calculates a linear interpolation

    73      * between a minimum and maximum value.

    74      *

    75      * @param aPos  Position. 0.0 corresponds to the minimum value, 1.0

    76      *              corresponds to the maximum value. Positions outside this

    77      *              range are allowed, which results in extrapolation.

    78      * @param aMin  Minimum value.

    79      * @param aMax  Maximum value.

    80      *

    81      * @return  Interpolated value.

    82      */

    83     IMPORT_C static TReal32 Interpolate(TReal32 aPos, TReal32 aMin, TReal32 aMax) __SOFTFP;

    84 

    85     /**

    86      * Wraps a value to a range.

    87      *

    88      * @param aValue  Reference to the value to wrap. Will be modified.

    89      * @param aLow    Range minimum. If aValue is equal to aLow, it will remain

    90      *                at aLow.

    91      * @param aHigh   Range maximum. If aValue is equal to aHigh, it will be

    92      *                wrapped to aLow.

    93      */

    94     IMPORT_C static void WrapValue(TReal32& aValue, TReal32 aLow, TReal32 aHigh) __SOFTFP;

    95 

    96     /**

    97      * Generates a random integer.

    98      *

    99      * @param aMin  Minimum possible value.

   100      * @param aMax  Maximum possible value.

   101      *

   102      * @return  Random integer between the minimum and maximum values,

   103      *          inclusive.

   104      */

   105     IMPORT_C static TInt RandomInt(TInt aMin, TInt aMax);

   106 

   107     /**

   108      * Generates a random real number.

   109      *

   110      * @param aMin  Minimum possible value.

   111      * @param aMax  Maximum possible value.

   112      *

   113      * @return  Random real number between the minimum and maximum values,

   114      *          inclusive.

   115      */

   116     IMPORT_C static TReal32 RandomReal(TReal32 aMin, TReal32 aMax) __SOFTFP;

   117 

   118     /**

   119      * Approximates the length of a 2D vector. This is done without

   120      * calculating a square root.

   121      *

   122      * @param aVector  2D vector as a point. The X and Y components are

   123      *                 interpreted as deltas.

   124      *

   125      * @return  Approximate length of the vector.

   126      */

   127     IMPORT_C static TReal32 QuickLength(TAlfRealPoint& aVector) __SOFTFP;

   128 

   129     /**

   130      * Approximates the length of a 2D vector. This is done without

   131      * calculating a square root.

   132      *

   133      * @param aDx  X delta of the vector.

   134      * @param aDy  Y delta of the vector.

   135      *

   136      * @return  Approximate length of the vector.

   137      */

   138     IMPORT_C static TReal32 QuickLength(TReal32 aDx, TReal32 aDy) __SOFTFP;

   139 

   140     /**

   141      * Normalizes a vector so that its length will be approximately 1.0.

   142      * This is done without calculating a square root.

   143      *

   144      * @param aVector  2D vector to be normalized as a point. The X and Y

   145      *                 components are interpreted as deltas. Will be modified.

   146      */

   147     IMPORT_C static void QuickNormalize(TAlfRealPoint& aVector);

   148 

   149     /**

   150      * Normalizes a vector so that its length will be approximately 1.0.

   151      * This is done without calculating a square root.

   152      *

   153      * @param aVector  3D vector to be normalized as a point (X, Y, Z components

   154      *                 as an array of TReal32). Will be modified.

   155      */

   156     IMPORT_C static void QuickNormalize(TReal32 aVector[3]) __SOFTFP;

   157 

   158     /**

   159      * Calculates a cross product of 3D vectors. aProduct = aA x aB.

   160      *

   161      * @param aA  3D vector.

   162      * @param aB  3D vector.

   163      * @param aProduct  3D vector where the cross product is returned.

   164      */

   165     IMPORT_C static void CrossProduct(const TReal32 aA[3], const TReal32 aB[3], TReal32 aProduct[3]) __SOFTFP;

   166 

   167     /**

   168      * Calculates a normal vector for a plane defined by three points.

   169      *

   170      * @param aPoints  Array of three 3D vectors. The first index is the number

   171      *                 of the vector, the second index is the vector component

   172      *                 (x, y, z).

   173      * @param aNormal  Resulting normal vector.

   174      */

   175     IMPORT_C static void NormalFromPoints(const TReal32 aPoints[3][3], TReal32 aNormal[3]) __SOFTFP;

   176 

   177     /**

   178      * Calculates a matrix that projects 3D points onto a plane. The name

   179      * ShadowMatrix comes from the intended usage: when used as a modelview

   180      * matrix, this matrix will flatten a 3D mesh onto a projected shadow.

   181      *

   182      * @param aPlanePoint  Point on the plane onto which the shadow is casted.

   183      * @param aPlaneNormal  Normal of the plane onto which the shadow is casted.

   184      * @param aLightPos  Position of the light source.

   185      * @param aDestMat  Resulting matrix.

   186      */

   187     IMPORT_C static void ShadowMatrix(const TReal32 aPlanePoint[3],

   188                                       const TReal32 aPlaneNormal[3],

   189                                       const TReal32 aLightPos[4],

   190                                       TReal32 aDestMat[16]) __SOFTFP;

   191 

   192     /**

   193      * Determines the amount of free memory in the system.

   194      *

   195      * @param aTotalMemory  If not NULL, the total amount of memory is

   196      *                      returned here.

   197      *

   198      * @return  Bytes of free memory.

   199      */

   200     IMPORT_C static TUint FreeMemory(TUint* aTotalMemory = 0);

   201 

   202     /**

   203      * Determines the native resolution of the device's screen.

   204      *

   205      * @return  Screen size in pixels.

   206      */

   207     IMPORT_C static TSize ScreenSize();

   208 

   209     /**

   210      * Finds the font that is the closest match to a font specification.

   211      * Note that the returned font instance must be released with

   212      * AlfUtil::ReleaseFont(). Deleting the returned font instance is not allowed.

   213      *

   214      * @param aFontSpec  Font specification.

   215      *

   216      * @return  Font instance. Must be released with a call to AlfUtil::ReleaseFont()

   217      *          when no longer needed.

   218      */

   219     IMPORT_C static CFont* NearestFontInTwipsL(const TFontSpec& aFontSpec);

   220 

   221     /**

   222      * Releases a font that was returned by NearestFontInTwipsL(). Must be

   223      * called when the font is no longer needed.

   224      *

   225      * @param aFont  Font returned by a previous allocation by AlfUtil.

   226      */

   227     IMPORT_C static void ReleaseFont(CFont* aFont);

   228 

   229     /**

   230      * Calculates a display size dependent length unit. This can be used for

   231      * layout calculations that should be independent of the display size.

   232      * For example, this could be the distance at which a shadow is drawn

   233      * behind text strings (assuming the font size also depends on display

   234      * size).

   235      *

   236      * @return  Length unit.

   237      */

   238     IMPORT_C static TReal32 LengthUnit() __SOFTFP;

   239 

   240     /**

   241      * Approximates the lightness of a color. The returned value is in range

   242      * 0...1, where 0.0 means the equivalent of black and 1.0 means the

   243      * equivalent of white. This is similar to the Value component in the HSV

   244      * color model (but not exactly the same).

   245      *

   246      * @param aColor  Color whose lightness is to be evaluated.

   247      *

   248      * @return  Lightness value.

   249      */

   250     IMPORT_C static TReal32 ColorLightness(const TRgb& aColor) __SOFTFP;

   251 

   252     /**

   253      * Resamples given FBS bitmap to new size (converting

   254      * color modes along the way..)

   255      * @param aSrcBitmap Source bitmap to resample.

   256      * @param aScaledBitmap Output bitmap. The original size of

   257      * this CFbsBitmap defines the size of the downscaled bitmap.

   258      */

   259     IMPORT_C static void ScaleFbsBitmapL(const CFbsBitmap & aSrcBitmap,

   260                                          CFbsBitmap & aScaledBitmap);

   261 

   262     /**

   263      * Converts separate mask and color bitmaps into single

   264      * EColor16MA (24bpp colour plus 8bpp alpha) bitmap.

   265      * @param aBitmap Source color channel bitmap.

   266      * @param aMaskBitmap The source alpha mask bitmap. Use either a black and

   267      * white (binary) mask bitmap, or if aMaskBitmap's display mode is EGray256,

   268      * alpha blending is used. Use of any other mode may result in unpredictable

   269      * results.

   270      * @param aCombinedBitmap Bitmap that will to contain the target

   271      * EColor16MA bitmap with color information from aBitmap and alpha information

   272      * from aMaskBitmap. NOTE: Must have color mode EColor16MA!

   273      */

   274     IMPORT_C static void CombineMaskFbsBitmapL(const CFbsBitmap & aSrcBitmap,

   275                                                const CFbsBitmap & aSrcMaskBitmap,

   276                                                CFbsBitmap & aCombinedBitmap);

   277 

   278     /**

   279      * Crops an area of FBS bitmap to new image. The size of the

   280      * copped bitmap defines the size of the area to crop.

   281      */

   282     IMPORT_C static void CropFbsBitmapL(const CFbsBitmap & aSrcBitmap,

   283                                         CFbsBitmap & aCroppedBitmap,

   284                                         TPoint aCropPosition);

   285 

   286     /**

   287      * Resamples given unsigned byte image data to new size. Uses box

   288      * filtering. Can be used to downscale too large textures, for example.

   289      *

   290      * @param aComponents Number of image components (color channels) in the

   291      * source image. Use 3 with RGB image and 4 with RGBA. The destination will

   292      * have the same amount of color channels after this operation.

   293      * @param aSrcSize Size (width and height) of the original image (aSrcBuffer),

   294      * in number of pixels (width) or rows (height).

   295      * @param aSrcBuffer Pointer to the source image data.

   296      * @param aDestSize Size (width and height) of the new scaled image,

   297      * (aDestBuffer) in number of pixels (width) or rows (height).

   298      * @param aDestBuffer Output parameter: Pointer where new scaled image

   299      * data will be stored. You must remember to allocate the space for the

   300      * buffer before calling this method.

   301      */

   302     IMPORT_C static void ScaleImage(TInt aComponents,

   303                                     const TSize& aSrcSize,

   304                                     const TUint8* aSrcBuffer,

   305                                     const TSize& aDestSize,

   306                                     TUint8* aDestBuffer);

   307 

   308     /**

   309      * Crops given unsigned byte image data. Can be used to split

   310      * large images to smaller sections.

   311      *

   312      * @param aComponents Number of image components (color channels) in the

   313      * source image. Use 3 with RGB image and 4 with RGBA. The destination will

   314      * have the same amount of color channels after this operation.

   315      * @param aSrcBufferSize Size (width and height) of the original image (aSrcBuffer),

   316      * in number of pixels (width) or rows (height).

   317      * @param aSrcBuffer Pointer to the source image data.

   318      * @param aCropOffset Cropping offset in the source image. Location of the

   319      * top-left corner of the cropped area, in pixels.

   320      * @param aCroppedSize Size of the cropped area. Is also the size of the

   321      * image in aDestBuffer. Width and height in pixels.

   322      * @param aDestBuffer Output parameter: Pointer where the cropped image

   323      * data will be stored. You must remember to allocate the space for the

   324      * buffer before calling this method.

   325      */

   326     IMPORT_C static void CropImage(TInt aComponents,

   327                                     const TSize& aSrcBufferSize,

   328                                     const TUint8* aSrcBuffer,

   329                                     const TPoint& aCropOffset,

   330                                     const TSize& aCroppedSize,

   331                                     TUint8* aDestBuffer);

   332 

   333 

   334     /**

   335      * Checks if aTag is included in aTagsColonSeparated. Tags are case-sensitive.

   336      *

   337      * @param aTagsColonSeparated  One or more tags separated by colons (:).

   338      *                             For example: "hello:world:tag3".

   339      * @param aTag  Tag to look for. For example: "world".

   340      *

   341      * @return  <code>ETrue</code>, if the tag was found in the colon-separated

   342      *          tags descriptor. <code>EFalse</code> otherwise.

   343      *

   344      * @see CAlfVisual::FindTag()

   345      */

   346     IMPORT_C static TBool TagMatches(const TDesC8& aTagsColonSeparated, const TDesC8& aTag);

   347 

   348     /**

   349      * Converts a bitmap to specified display mode.

   350      * This method converts a bitmap in any display mode to specified display mode.

   351      * Method creates a new bitmap, leaves it in cleanup stack and returns it.

   352      *

   353      * @param aBitmap The bitmap to be converted.

   354      * @param aDisplaymode The target display mode to convert the bitmap into.

   355      * @return Newly created conversion of the source bitmap.

   356      */

   357     IMPORT_C static CFbsBitmap* ConvertBitmapToDisplayModeLC( const CFbsBitmap& aBitmap, const TDisplayMode& aDisplaymode );

   358 

   359  

   360     /**

   361      * @deprecated <b>Always returns KAknsIIDNone<\b>

   362      * 

   363      * Retrieves the TAknsItemID corresponding to the Textual skin identifier

   364      *

   365      * @param aEnv Alf Environment variable

   366      * @param aSkinId The textual identifier for which corresponding TAknsItemID is

   367      *	required

   368      *

   369      * @return TAknsItemID object corresponding to aSkinId

   370      */

   371 	 IMPORT_C static TAknsItemID ThemeItemIdL(CAlfEnv& aEnv, const TDesC& aSkinId );

   372 

   373     /** @endAPI */

   374 

   375     /**

   376      * Asserts if the given condition is false.

   377      */

   378     static void Assert(TBool aCondition);

   379 

   380     /**

   381      * Rounds a float (TReal32) correctly into an integer (TInt). Takes care of both negative

   382      * and positive real number.

   383      * 

   384      * @param aVal The value to be rounded to the closest integer.

   385      * @return Rounded integer.

   386      */

   387     static TInt RoundFloatToInt(TReal32 aVal);

   388     

   389     };

   390 

   391 

   392 

   393 #endif // C_ALFUTIL_H