1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/graphics/graphicsresourceservices/graphicsresourceinterface/inc/sgimage.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,251 @@
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 "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.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 +// Graphics Resource - images
1.18 +//
1.19 +
1.20 +#ifndef SGIMAGE_H
1.21 +#define SGIMAGE_H
1.22 +
1.23 +#include <sgresource/sgresource.h>
1.24 +
1.25 +/**
1.26 +A class that encapsulates the basic attributes of an image.
1.27 +It is used both to create images and to obtain information about them.
1.28 +The basic attributes of an image cannot be changed after creation.
1.29 +For an instance of TSgImageInfo to be valid the following conditions must be satisfied:
1.30 + - The width and height in iSizeInPixels must both be greater than zero.
1.31 + - iPixelFormat must not be EUidPixelFormatUnknown.
1.32 + - iUsage must have at least one usage bit set.
1.33 +*/
1.34 +NONSHARABLE_CLASS(TSgImageInfo)
1.35 + {
1.36 +public:
1.37 + /**
1.38 + Default constructor.
1.39 + Data members remain uninitialised.
1.40 + */
1.41 + inline TSgImageInfo();
1.42 +
1.43 + /**
1.44 + Constructor which initialises data members to the given values.
1.45 + */
1.46 + inline TSgImageInfo(const TSize& aSizeInPixels, TInt aPixelFormat, TUint32 aUsage);
1.47 +public:
1.48 + /** The size of the image in pixels.*/
1.49 + TSize iSizeInPixels;
1.50 + /**
1.51 + UID representing the pixel format of the image.
1.52 + The values enumerated in TSgPixelFormat are guaranteed to be supported by
1.53 + every implementation of the Graphics Resource API but additional pixel
1.54 + formats from TUidPixelFormat may be supported by some implementations.
1.55 + @see RSgImage::GetPixelFormats().
1.56 + */
1.57 + TInt iPixelFormat;
1.58 + /** The possible usage of the image as a combination of bits from TSgUsageBits.*/
1.59 + TUint32 iUsage;
1.60 + };
1.61 +
1.62 +/**
1.63 +The drawable resource type associated with images.
1.64 +*/
1.65 +const TUid KSgImageTypeUid = {0x10285A73};
1.66 +
1.67 +/**
1.68 +An image handle.
1.69 +It inherits all the general handle functionality from RSgDrawable.
1.70 +An image is a drawable resource containing a two-dimensional pixel array.
1.71 +Its basic attributes are the size in pixels, the pixel format and the usage.
1.72 +The usage for which an image is created must be declared so that it can be properly allocated.
1.73 +The attributes of an image cannot be changed after creation.
1.74 +Instances of RSgImage can be constructed before RSgDriver::Open() is called and
1.75 +the implementation of the Graphics Resource API is initialised in the context
1.76 +of the process, but most attempts to call a function of RSgImage will panic
1.77 +with category “SGRES” and code 1 both in debug and release builds if the
1.78 +implementation of the Graphics Resource API is not initialised in the context
1.79 +of the process. Any attempt to call a function of RSgImage on an invalid handle
1.80 +will panic with category “SGRES” and code 3 both in debug and release builds.
1.81 +*/
1.82 +NONSHARABLE_CLASS(RSgImage): public RSgDrawable
1.83 + {
1.84 +public:
1.85 + /**
1.86 + Default constructor which sets iHandleType to KSgImageTypeUid and
1.87 + creates null image handles.
1.88 + */
1.89 + inline RSgImage();
1.90 +
1.91 + /**
1.92 + Creates an image with the basic attributes given by the parameter aInfo
1.93 + and the initial contents given by the parameters aDataAddress and
1.94 + aDataStride, and returns KErrNone if successful.
1.95 +
1.96 + @pre An RSgDriver handle has been opened in the context of the process.
1.97 + @pre The instance of RSgImage is a null handle.
1.98 + @pre The parameter aInfo is valid.
1.99 + @pre If the parameter aDataAddress is not NULL then the parameter aDataStride
1.100 + is not zero and its absolute value is equal to or greater than the
1.101 + minimum number of bytes needed for a row of pixel data.
1.102 + @post The created image has an initial reference count of one.
1.103 + @param aInfo An instance of TSgImageInfo with the basic attributes of the
1.104 + image to be created.
1.105 + @param aDataAddress The base address of the pixel data used to populate the
1.106 + image to be created. The pixel format of the data must be the exact
1.107 + pixel format given in aInfo but the implementation of Graphics
1.108 + Resource may convert the data to the internal pixel format of the image,
1.109 + which could be any pixel format without loss of data.
1.110 + If aDataAddress is NULL the initial contents of the image are undefined.
1.111 + @param aDataStride The number of bytes between the rows of the pixel data
1.112 + pointed to by aDataAddress. It can be a positive value to indicate
1.113 + top-down ordering of the rows of pixel data or a negative value to
1.114 + indicate bottom-up ordering of the rows of pixel data. Inside each row
1.115 + of pixel data, ordering of pixels is always left-to-right.
1.116 + @param aAttributes A pointer to an array of extension attributes, if allowed
1.117 + by any extension of the Graphics Resource API, or NULL otherwise.
1.118 + @return KErrNone if successful;
1.119 + KErrInUse if the instance of RSgImage is an open handle;
1.120 + KErrArgument if either
1.121 + 1. the parameter aInfo is not valid or
1.122 + 2. the parameter aDataAddress is not NULL and the parameter aDataStride
1.123 + is zero or its absolute value is less than the minimum number of bytes
1.124 + needed for a row of pixel data;
1.125 + KErrTooBig if the size given by the parameter aInfo is greater than
1.126 + the maximum image size supported by the implementation of Graphics
1.127 + Resource API. The maximum image size supported by an implementation of
1.128 + the Graphics Resource API is at least 2048 by 2048 pixels;
1.129 + KErrNotSupported if either
1.130 + 1. the combination of pixel format and usages given by the parameter
1.131 + aInfo is not supported by the implementation of the Graphics Resource
1.132 + API or
1.133 + 2. the parameter aAttributes is not NULL and one or more of the extension
1.134 + attributes in the array is not defined by any extension of the Graphics
1.135 + Resource API;
1.136 + KErrNoMemory if there is not enough system memory to create the image;
1.137 + KErrNoGraphicsMemory if there is not enough specialised graphics memory
1.138 + to create the image.
1.139 + @panic SGRES 1 No RSgDriver handle has been opened in the context of the process.
1.140 + */
1.141 + IMPORT_C TInt Create(const TSgImageInfo& aInfo,
1.142 + const TAny* aDataAddress = NULL,
1.143 + TInt aDataStride = 0,
1.144 + const TSgAttributeArrayBase* aAttributes = NULL);
1.145 +
1.146 + /**
1.147 + Creates an image with the basic attributes given by the parameter aInfo
1.148 + and the initial contents copied from an existing image given by the
1.149 + parameter aImage, and returns KErrNone if successful.
1.150 +
1.151 + @pre An RSgDriver handle has been opened in the context of the process.
1.152 + @pre The instance of RSgImage is a null handle.
1.153 + @pre The parameter aInfo is valid.
1.154 + @pre The parameter aImage is an open handle
1.155 + @pre The size and the pixel format given by aInfo must be the same as
1.156 + the size and the pixel format of the existing image.
1.157 + @post The created image has an initial reference count of one.
1.158 + @param aInfo An instance of TSgImageInfo with the basic attributes of the
1.159 + image to be created.
1.160 + @param aImage A handle to the existing image.
1.161 + @param aAttributes A pointer to an array of extension attributes, if allowed
1.162 + by any extension of the Graphics Resource API, or NULL otherwise.
1.163 + @return KErrNone if successful;
1.164 + KErrInUse if the instance of RSgImage is an open handle;
1.165 + KErrArgument if either
1.166 + 1. the parameter aInfo is not valid or
1.167 + 2. the parameter aImage is a null handle;
1.168 + KErrNotSupported if either
1.169 + 1. the combination of pixel format and usages given by the parameter
1.170 + aInfo is not supported by the implementation of the Graphics Resource
1.171 + API or
1.172 + 2. the size and the pixel format given by the parameter aInfo are
1.173 + not the same as the size and the pixel format of the existing image or
1.174 + 3. the parameter aAttributes is not NULL and one or more of the extension
1.175 + attributes in the array is not defined by any extension of the Graphics
1.176 + Resource API;
1.177 + KErrNoMemory if there is not enough system memory to create the image;
1.178 + KErrNoGraphicsMemory if there is not enough specialised graphics memory
1.179 + to create the image.
1.180 + @panic SGRES 1 No RSgDriver handle has been opened in the context of the process.
1.181 + @panic SGRES 3 aImage is an invalid handle.
1.182 + */
1.183 + IMPORT_C TInt Create(const TSgImageInfo& aInfo,
1.184 + const RSgImage& aImage,
1.185 + const TSgAttributeArrayBase* aAttributes = NULL);
1.186 +
1.187 + /**
1.188 + Retrieves the values of the basic attributes of an image and returns
1.189 + KErrNone if successful.
1.190 +
1.191 + @pre An RSgDriver handle has been opened in the context of the process.
1.192 + @pre The instance of RSgImage is an open handle.
1.193 + @param[out] aInfo An instance of TSgImageInfo that on return contains the
1.194 + values of the basic attributes of the image.
1.195 + @return KErrNone if successful;
1.196 + KErrBadHandle if the instance of RSgImage is a null handle.
1.197 + @panic SGRES 1 No RSgDriver handle has been opened in the context of the process.
1.198 + @panic SGRES 3 The instance of RSgImage is an invalid handle.
1.199 + */
1.200 + IMPORT_C TInt GetInfo(TSgImageInfo& aInfo) const;
1.201 +
1.202 + /**
1.203 + Retrieves the value of an extension attribute of an image and returns
1.204 + KErrNone if successful.
1.205 +
1.206 + @pre An RSgDriver handle has been opened in the context of the process.
1.207 + @pre The instance of RSgImage is an open handle.
1.208 + @param[in] aUid The UID of the extension attribute.
1.209 + @param[out] aInfo A reference to a variable that on return holds the value
1.210 + of the extension attribute.
1.211 + @return KErrNone if successful;
1.212 + KErrBadHandle if the instance of RSgImage is a null handle;
1.213 + KErrNotSupported if no extension of the Graphics Resource API defines
1.214 + an extension attribute that applies to the image with the given UID.
1.215 + @panic SGRES 1 No RSgDriver handle has been opened in the context of the process.
1.216 + @panic SGRES 3 The instance of RSgImage is an invalid handle.
1.217 + */
1.218 + IMPORT_C TInt GetAttribute(TUid aUid, TInt& aValue) const;
1.219 +
1.220 + /**
1.221 + Retrieves the list of pixel formats supported by the implementation
1.222 + of the Graphics Resource API for images with the usage given by the
1.223 + parameter aUsage and returns KErrNone if successful.
1.224 + This is a utility function typically called before creating images.
1.225 +
1.226 + @pre The parameter aUsage has at least one usage bit set.
1.227 + @pre The number of elements in the array referenced by the parameter
1.228 + aPixelFormats is zero.
1.229 + @param[in] aUsage A combination of usages from TSgUsageBits.
1.230 + @param[out] aPixelFormats A reference to an array that on input must be empty
1.231 + and on return contains the list of supported pixel formats.
1.232 + @param[in] aAttributes A pointer to an array with extension image attributes,
1.233 + if any extension of the Graphics Resource API defines extension image
1.234 + attributes that have an impact on the list of supported pixel formats,
1.235 + or NULL otherwise.
1.236 + @return KErrNone if successful;
1.237 + KErrArgument if either
1.238 + 1. the parameter aUsage does not have at least one usage bit set or
1.239 + 2. the number of elements in the array referenced by the parameter
1.240 + aPixelFormats was not zero before calling this function;
1.241 + KErrNotSupported if the parameter aAttributes is not NULL and one or
1.242 + more of the extension attributes in the array is not defined by any
1.243 + extension of the Graphics Resource API;
1.244 + KErrNoMemory if there is not enough system memory to add a pixel format
1.245 + to the array referenced by the parameter aPixelFormats.
1.246 + */
1.247 + IMPORT_C static TInt GetPixelFormats(TUint32 aUsage,
1.248 + RArray<TInt>& aPixelFormats,
1.249 + const TSgAttributeArrayBase* aAttributes = NULL);
1.250 + };
1.251 +
1.252 +#include <sgresource/sgimage.inl>
1.253 +
1.254 +#endif // SGIMAGE_H