sl@0: // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). sl@0: // All rights reserved. sl@0: // This component and the accompanying materials are made available sl@0: // under the terms of "Eclipse Public License v1.0" sl@0: // which accompanies this distribution, and is available sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html". sl@0: // sl@0: // Initial Contributors: sl@0: // Nokia Corporation - initial contribution. sl@0: // sl@0: // Contributors: sl@0: // sl@0: // Description: sl@0: // Graphics Resource - images sl@0: // sl@0: sl@0: #ifndef SGIMAGE_H sl@0: #define SGIMAGE_H sl@0: sl@0: #include sl@0: sl@0: /** sl@0: A class that encapsulates the basic attributes of an image. sl@0: It is used both to create images and to obtain information about them. sl@0: The basic attributes of an image cannot be changed after creation. sl@0: For an instance of TSgImageInfo to be valid the following conditions must be satisfied: sl@0: - The width and height in iSizeInPixels must both be greater than zero. sl@0: - iPixelFormat must not be EUidPixelFormatUnknown. sl@0: - iUsage must have at least one usage bit set. sl@0: */ sl@0: NONSHARABLE_CLASS(TSgImageInfo) sl@0: { sl@0: public: sl@0: /** sl@0: Default constructor. sl@0: Data members remain uninitialised. sl@0: */ sl@0: inline TSgImageInfo(); sl@0: sl@0: /** sl@0: Constructor which initialises data members to the given values. sl@0: */ sl@0: inline TSgImageInfo(const TSize& aSizeInPixels, TInt aPixelFormat, TUint32 aUsage); sl@0: public: sl@0: /** The size of the image in pixels.*/ sl@0: TSize iSizeInPixels; sl@0: /** sl@0: UID representing the pixel format of the image. sl@0: The values enumerated in TSgPixelFormat are guaranteed to be supported by sl@0: every implementation of the Graphics Resource API but additional pixel sl@0: formats from TUidPixelFormat may be supported by some implementations. sl@0: @see RSgImage::GetPixelFormats(). sl@0: */ sl@0: TInt iPixelFormat; sl@0: /** The possible usage of the image as a combination of bits from TSgUsageBits.*/ sl@0: TUint32 iUsage; sl@0: }; sl@0: sl@0: /** sl@0: The drawable resource type associated with images. sl@0: */ sl@0: const TUid KSgImageTypeUid = {0x10285A73}; sl@0: sl@0: /** sl@0: An image handle. sl@0: It inherits all the general handle functionality from RSgDrawable. sl@0: An image is a drawable resource containing a two-dimensional pixel array. sl@0: Its basic attributes are the size in pixels, the pixel format and the usage. sl@0: The usage for which an image is created must be declared so that it can be properly allocated. sl@0: The attributes of an image cannot be changed after creation. sl@0: Instances of RSgImage can be constructed before RSgDriver::Open() is called and sl@0: the implementation of the Graphics Resource API is initialised in the context sl@0: of the process, but most attempts to call a function of RSgImage will panic sl@0: with category “SGRES” and code 1 both in debug and release builds if the sl@0: implementation of the Graphics Resource API is not initialised in the context sl@0: of the process. Any attempt to call a function of RSgImage on an invalid handle sl@0: will panic with category “SGRES” and code 3 both in debug and release builds. sl@0: */ sl@0: NONSHARABLE_CLASS(RSgImage): public RSgDrawable sl@0: { sl@0: public: sl@0: /** sl@0: Default constructor which sets iHandleType to KSgImageTypeUid and sl@0: creates null image handles. sl@0: */ sl@0: inline RSgImage(); sl@0: sl@0: /** sl@0: Creates an image with the basic attributes given by the parameter aInfo sl@0: and the initial contents given by the parameters aDataAddress and sl@0: aDataStride, and returns KErrNone if successful. sl@0: sl@0: @pre An RSgDriver handle has been opened in the context of the process. sl@0: @pre The instance of RSgImage is a null handle. sl@0: @pre The parameter aInfo is valid. sl@0: @pre If the parameter aDataAddress is not NULL then the parameter aDataStride sl@0: is not zero and its absolute value is equal to or greater than the sl@0: minimum number of bytes needed for a row of pixel data. sl@0: @post The created image has an initial reference count of one. sl@0: @param aInfo An instance of TSgImageInfo with the basic attributes of the sl@0: image to be created. sl@0: @param aDataAddress The base address of the pixel data used to populate the sl@0: image to be created. The pixel format of the data must be the exact sl@0: pixel format given in aInfo but the implementation of Graphics sl@0: Resource may convert the data to the internal pixel format of the image, sl@0: which could be any pixel format without loss of data. sl@0: If aDataAddress is NULL the initial contents of the image are undefined. sl@0: @param aDataStride The number of bytes between the rows of the pixel data sl@0: pointed to by aDataAddress. It can be a positive value to indicate sl@0: top-down ordering of the rows of pixel data or a negative value to sl@0: indicate bottom-up ordering of the rows of pixel data. Inside each row sl@0: of pixel data, ordering of pixels is always left-to-right. sl@0: @param aAttributes A pointer to an array of extension attributes, if allowed sl@0: by any extension of the Graphics Resource API, or NULL otherwise. sl@0: @return KErrNone if successful; sl@0: KErrInUse if the instance of RSgImage is an open handle; sl@0: KErrArgument if either sl@0: 1. the parameter aInfo is not valid or sl@0: 2. the parameter aDataAddress is not NULL and the parameter aDataStride sl@0: is zero or its absolute value is less than the minimum number of bytes sl@0: needed for a row of pixel data; sl@0: KErrTooBig if the size given by the parameter aInfo is greater than sl@0: the maximum image size supported by the implementation of Graphics sl@0: Resource API. The maximum image size supported by an implementation of sl@0: the Graphics Resource API is at least 2048 by 2048 pixels; sl@0: KErrNotSupported if either sl@0: 1. the combination of pixel format and usages given by the parameter sl@0: aInfo is not supported by the implementation of the Graphics Resource sl@0: API or sl@0: 2. the parameter aAttributes is not NULL and one or more of the extension sl@0: attributes in the array is not defined by any extension of the Graphics sl@0: Resource API; sl@0: KErrNoMemory if there is not enough system memory to create the image; sl@0: KErrNoGraphicsMemory if there is not enough specialised graphics memory sl@0: to create the image. sl@0: @panic SGRES 1 No RSgDriver handle has been opened in the context of the process. sl@0: */ sl@0: IMPORT_C TInt Create(const TSgImageInfo& aInfo, sl@0: const TAny* aDataAddress = NULL, sl@0: TInt aDataStride = 0, sl@0: const TSgAttributeArrayBase* aAttributes = NULL); sl@0: sl@0: /** sl@0: Creates an image with the basic attributes given by the parameter aInfo sl@0: and the initial contents copied from an existing image given by the sl@0: parameter aImage, and returns KErrNone if successful. sl@0: sl@0: @pre An RSgDriver handle has been opened in the context of the process. sl@0: @pre The instance of RSgImage is a null handle. sl@0: @pre The parameter aInfo is valid. sl@0: @pre The parameter aImage is an open handle sl@0: @pre The size and the pixel format given by aInfo must be the same as sl@0: the size and the pixel format of the existing image. sl@0: @post The created image has an initial reference count of one. sl@0: @param aInfo An instance of TSgImageInfo with the basic attributes of the sl@0: image to be created. sl@0: @param aImage A handle to the existing image. sl@0: @param aAttributes A pointer to an array of extension attributes, if allowed sl@0: by any extension of the Graphics Resource API, or NULL otherwise. sl@0: @return KErrNone if successful; sl@0: KErrInUse if the instance of RSgImage is an open handle; sl@0: KErrArgument if either sl@0: 1. the parameter aInfo is not valid or sl@0: 2. the parameter aImage is a null handle; sl@0: KErrNotSupported if either sl@0: 1. the combination of pixel format and usages given by the parameter sl@0: aInfo is not supported by the implementation of the Graphics Resource sl@0: API or sl@0: 2. the size and the pixel format given by the parameter aInfo are sl@0: not the same as the size and the pixel format of the existing image or sl@0: 3. the parameter aAttributes is not NULL and one or more of the extension sl@0: attributes in the array is not defined by any extension of the Graphics sl@0: Resource API; sl@0: KErrNoMemory if there is not enough system memory to create the image; sl@0: KErrNoGraphicsMemory if there is not enough specialised graphics memory sl@0: to create the image. sl@0: @panic SGRES 1 No RSgDriver handle has been opened in the context of the process. sl@0: @panic SGRES 3 aImage is an invalid handle. sl@0: */ sl@0: IMPORT_C TInt Create(const TSgImageInfo& aInfo, sl@0: const RSgImage& aImage, sl@0: const TSgAttributeArrayBase* aAttributes = NULL); sl@0: sl@0: /** sl@0: Retrieves the values of the basic attributes of an image and returns sl@0: KErrNone if successful. sl@0: sl@0: @pre An RSgDriver handle has been opened in the context of the process. sl@0: @pre The instance of RSgImage is an open handle. sl@0: @param[out] aInfo An instance of TSgImageInfo that on return contains the sl@0: values of the basic attributes of the image. sl@0: @return KErrNone if successful; sl@0: KErrBadHandle if the instance of RSgImage is a null handle. sl@0: @panic SGRES 1 No RSgDriver handle has been opened in the context of the process. sl@0: @panic SGRES 3 The instance of RSgImage is an invalid handle. sl@0: */ sl@0: IMPORT_C TInt GetInfo(TSgImageInfo& aInfo) const; sl@0: sl@0: /** sl@0: Retrieves the value of an extension attribute of an image and returns sl@0: KErrNone if successful. sl@0: sl@0: @pre An RSgDriver handle has been opened in the context of the process. sl@0: @pre The instance of RSgImage is an open handle. sl@0: @param[in] aUid The UID of the extension attribute. sl@0: @param[out] aInfo A reference to a variable that on return holds the value sl@0: of the extension attribute. sl@0: @return KErrNone if successful; sl@0: KErrBadHandle if the instance of RSgImage is a null handle; sl@0: KErrNotSupported if no extension of the Graphics Resource API defines sl@0: an extension attribute that applies to the image with the given UID. sl@0: @panic SGRES 1 No RSgDriver handle has been opened in the context of the process. sl@0: @panic SGRES 3 The instance of RSgImage is an invalid handle. sl@0: */ sl@0: IMPORT_C TInt GetAttribute(TUid aUid, TInt& aValue) const; sl@0: sl@0: /** sl@0: Retrieves the list of pixel formats supported by the implementation sl@0: of the Graphics Resource API for images with the usage given by the sl@0: parameter aUsage and returns KErrNone if successful. sl@0: This is a utility function typically called before creating images. sl@0: sl@0: @pre The parameter aUsage has at least one usage bit set. sl@0: @pre The number of elements in the array referenced by the parameter sl@0: aPixelFormats is zero. sl@0: @param[in] aUsage A combination of usages from TSgUsageBits. sl@0: @param[out] aPixelFormats A reference to an array that on input must be empty sl@0: and on return contains the list of supported pixel formats. sl@0: @param[in] aAttributes A pointer to an array with extension image attributes, sl@0: if any extension of the Graphics Resource API defines extension image sl@0: attributes that have an impact on the list of supported pixel formats, sl@0: or NULL otherwise. sl@0: @return KErrNone if successful; sl@0: KErrArgument if either sl@0: 1. the parameter aUsage does not have at least one usage bit set or sl@0: 2. the number of elements in the array referenced by the parameter sl@0: aPixelFormats was not zero before calling this function; sl@0: KErrNotSupported if the parameter aAttributes is not NULL and one or sl@0: more of the extension attributes in the array is not defined by any sl@0: extension of the Graphics Resource API; sl@0: KErrNoMemory if there is not enough system memory to add a pixel format sl@0: to the array referenced by the parameter aPixelFormats. sl@0: */ sl@0: IMPORT_C static TInt GetPixelFormats(TUint32 aUsage, sl@0: RArray& aPixelFormats, sl@0: const TSgAttributeArrayBase* aAttributes = NULL); sl@0: }; sl@0: sl@0: #include sl@0: sl@0: #endif // SGIMAGE_H