|
1 // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // Graphics Resource - images |
|
15 // |
|
16 |
|
17 #ifndef SGIMAGE_H |
|
18 #define SGIMAGE_H |
|
19 |
|
20 #include <sgresource/sgresource.h> |
|
21 |
|
22 /** |
|
23 A class that encapsulates the basic attributes of an image. |
|
24 It is used both to create images and to obtain information about them. |
|
25 The basic attributes of an image cannot be changed after creation. |
|
26 For an instance of TSgImageInfo to be valid the following conditions must be satisfied: |
|
27 - The width and height in iSizeInPixels must both be greater than zero. |
|
28 - iPixelFormat must not be EUidPixelFormatUnknown. |
|
29 - iUsage must have at least one usage bit set. |
|
30 */ |
|
31 NONSHARABLE_CLASS(TSgImageInfo) |
|
32 { |
|
33 public: |
|
34 /** |
|
35 Default constructor. |
|
36 Data members remain uninitialised. |
|
37 */ |
|
38 inline TSgImageInfo(); |
|
39 |
|
40 /** |
|
41 Constructor which initialises data members to the given values. |
|
42 */ |
|
43 inline TSgImageInfo(const TSize& aSizeInPixels, TInt aPixelFormat, TUint32 aUsage); |
|
44 public: |
|
45 /** The size of the image in pixels.*/ |
|
46 TSize iSizeInPixels; |
|
47 /** |
|
48 UID representing the pixel format of the image. |
|
49 The values enumerated in TSgPixelFormat are guaranteed to be supported by |
|
50 every implementation of the Graphics Resource API but additional pixel |
|
51 formats from TUidPixelFormat may be supported by some implementations. |
|
52 @see RSgImage::GetPixelFormats(). |
|
53 */ |
|
54 TInt iPixelFormat; |
|
55 /** The possible usage of the image as a combination of bits from TSgUsageBits.*/ |
|
56 TUint32 iUsage; |
|
57 }; |
|
58 |
|
59 /** |
|
60 The drawable resource type associated with images. |
|
61 */ |
|
62 const TUid KSgImageTypeUid = {0x10285A73}; |
|
63 |
|
64 /** |
|
65 An image handle. |
|
66 It inherits all the general handle functionality from RSgDrawable. |
|
67 An image is a drawable resource containing a two-dimensional pixel array. |
|
68 Its basic attributes are the size in pixels, the pixel format and the usage. |
|
69 The usage for which an image is created must be declared so that it can be properly allocated. |
|
70 The attributes of an image cannot be changed after creation. |
|
71 Instances of RSgImage can be constructed before RSgDriver::Open() is called and |
|
72 the implementation of the Graphics Resource API is initialised in the context |
|
73 of the process, but most attempts to call a function of RSgImage will panic |
|
74 with category “SGRES” and code 1 both in debug and release builds if the |
|
75 implementation of the Graphics Resource API is not initialised in the context |
|
76 of the process. Any attempt to call a function of RSgImage on an invalid handle |
|
77 will panic with category “SGRES” and code 3 both in debug and release builds. |
|
78 */ |
|
79 NONSHARABLE_CLASS(RSgImage): public RSgDrawable |
|
80 { |
|
81 public: |
|
82 /** |
|
83 Default constructor which sets iHandleType to KSgImageTypeUid and |
|
84 creates null image handles. |
|
85 */ |
|
86 inline RSgImage(); |
|
87 |
|
88 /** |
|
89 Creates an image with the basic attributes given by the parameter aInfo |
|
90 and the initial contents given by the parameters aDataAddress and |
|
91 aDataStride, and returns KErrNone if successful. |
|
92 |
|
93 @pre An RSgDriver handle has been opened in the context of the process. |
|
94 @pre The instance of RSgImage is a null handle. |
|
95 @pre The parameter aInfo is valid. |
|
96 @pre If the parameter aDataAddress is not NULL then the parameter aDataStride |
|
97 is not zero and its absolute value is equal to or greater than the |
|
98 minimum number of bytes needed for a row of pixel data. |
|
99 @post The created image has an initial reference count of one. |
|
100 @param aInfo An instance of TSgImageInfo with the basic attributes of the |
|
101 image to be created. |
|
102 @param aDataAddress The base address of the pixel data used to populate the |
|
103 image to be created. The pixel format of the data must be the exact |
|
104 pixel format given in aInfo but the implementation of Graphics |
|
105 Resource may convert the data to the internal pixel format of the image, |
|
106 which could be any pixel format without loss of data. |
|
107 If aDataAddress is NULL the initial contents of the image are undefined. |
|
108 @param aDataStride The number of bytes between the rows of the pixel data |
|
109 pointed to by aDataAddress. It can be a positive value to indicate |
|
110 top-down ordering of the rows of pixel data or a negative value to |
|
111 indicate bottom-up ordering of the rows of pixel data. Inside each row |
|
112 of pixel data, ordering of pixels is always left-to-right. |
|
113 @param aAttributes A pointer to an array of extension attributes, if allowed |
|
114 by any extension of the Graphics Resource API, or NULL otherwise. |
|
115 @return KErrNone if successful; |
|
116 KErrInUse if the instance of RSgImage is an open handle; |
|
117 KErrArgument if either |
|
118 1. the parameter aInfo is not valid or |
|
119 2. the parameter aDataAddress is not NULL and the parameter aDataStride |
|
120 is zero or its absolute value is less than the minimum number of bytes |
|
121 needed for a row of pixel data; |
|
122 KErrTooBig if the size given by the parameter aInfo is greater than |
|
123 the maximum image size supported by the implementation of Graphics |
|
124 Resource API. The maximum image size supported by an implementation of |
|
125 the Graphics Resource API is at least 2048 by 2048 pixels; |
|
126 KErrNotSupported if either |
|
127 1. the combination of pixel format and usages given by the parameter |
|
128 aInfo is not supported by the implementation of the Graphics Resource |
|
129 API or |
|
130 2. the parameter aAttributes is not NULL and one or more of the extension |
|
131 attributes in the array is not defined by any extension of the Graphics |
|
132 Resource API; |
|
133 KErrNoMemory if there is not enough system memory to create the image; |
|
134 KErrNoGraphicsMemory if there is not enough specialised graphics memory |
|
135 to create the image. |
|
136 @panic SGRES 1 No RSgDriver handle has been opened in the context of the process. |
|
137 */ |
|
138 IMPORT_C TInt Create(const TSgImageInfo& aInfo, |
|
139 const TAny* aDataAddress = NULL, |
|
140 TInt aDataStride = 0, |
|
141 const TSgAttributeArrayBase* aAttributes = NULL); |
|
142 |
|
143 /** |
|
144 Creates an image with the basic attributes given by the parameter aInfo |
|
145 and the initial contents copied from an existing image given by the |
|
146 parameter aImage, and returns KErrNone if successful. |
|
147 |
|
148 @pre An RSgDriver handle has been opened in the context of the process. |
|
149 @pre The instance of RSgImage is a null handle. |
|
150 @pre The parameter aInfo is valid. |
|
151 @pre The parameter aImage is an open handle |
|
152 @pre The size and the pixel format given by aInfo must be the same as |
|
153 the size and the pixel format of the existing image. |
|
154 @post The created image has an initial reference count of one. |
|
155 @param aInfo An instance of TSgImageInfo with the basic attributes of the |
|
156 image to be created. |
|
157 @param aImage A handle to the existing image. |
|
158 @param aAttributes A pointer to an array of extension attributes, if allowed |
|
159 by any extension of the Graphics Resource API, or NULL otherwise. |
|
160 @return KErrNone if successful; |
|
161 KErrInUse if the instance of RSgImage is an open handle; |
|
162 KErrArgument if either |
|
163 1. the parameter aInfo is not valid or |
|
164 2. the parameter aImage is a null handle; |
|
165 KErrNotSupported if either |
|
166 1. the combination of pixel format and usages given by the parameter |
|
167 aInfo is not supported by the implementation of the Graphics Resource |
|
168 API or |
|
169 2. the size and the pixel format given by the parameter aInfo are |
|
170 not the same as the size and the pixel format of the existing image or |
|
171 3. the parameter aAttributes is not NULL and one or more of the extension |
|
172 attributes in the array is not defined by any extension of the Graphics |
|
173 Resource API; |
|
174 KErrNoMemory if there is not enough system memory to create the image; |
|
175 KErrNoGraphicsMemory if there is not enough specialised graphics memory |
|
176 to create the image. |
|
177 @panic SGRES 1 No RSgDriver handle has been opened in the context of the process. |
|
178 @panic SGRES 3 aImage is an invalid handle. |
|
179 */ |
|
180 IMPORT_C TInt Create(const TSgImageInfo& aInfo, |
|
181 const RSgImage& aImage, |
|
182 const TSgAttributeArrayBase* aAttributes = NULL); |
|
183 |
|
184 /** |
|
185 Retrieves the values of the basic attributes of an image and returns |
|
186 KErrNone if successful. |
|
187 |
|
188 @pre An RSgDriver handle has been opened in the context of the process. |
|
189 @pre The instance of RSgImage is an open handle. |
|
190 @param[out] aInfo An instance of TSgImageInfo that on return contains the |
|
191 values of the basic attributes of the image. |
|
192 @return KErrNone if successful; |
|
193 KErrBadHandle if the instance of RSgImage is a null handle. |
|
194 @panic SGRES 1 No RSgDriver handle has been opened in the context of the process. |
|
195 @panic SGRES 3 The instance of RSgImage is an invalid handle. |
|
196 */ |
|
197 IMPORT_C TInt GetInfo(TSgImageInfo& aInfo) const; |
|
198 |
|
199 /** |
|
200 Retrieves the value of an extension attribute of an image and returns |
|
201 KErrNone if successful. |
|
202 |
|
203 @pre An RSgDriver handle has been opened in the context of the process. |
|
204 @pre The instance of RSgImage is an open handle. |
|
205 @param[in] aUid The UID of the extension attribute. |
|
206 @param[out] aInfo A reference to a variable that on return holds the value |
|
207 of the extension attribute. |
|
208 @return KErrNone if successful; |
|
209 KErrBadHandle if the instance of RSgImage is a null handle; |
|
210 KErrNotSupported if no extension of the Graphics Resource API defines |
|
211 an extension attribute that applies to the image with the given UID. |
|
212 @panic SGRES 1 No RSgDriver handle has been opened in the context of the process. |
|
213 @panic SGRES 3 The instance of RSgImage is an invalid handle. |
|
214 */ |
|
215 IMPORT_C TInt GetAttribute(TUid aUid, TInt& aValue) const; |
|
216 |
|
217 /** |
|
218 Retrieves the list of pixel formats supported by the implementation |
|
219 of the Graphics Resource API for images with the usage given by the |
|
220 parameter aUsage and returns KErrNone if successful. |
|
221 This is a utility function typically called before creating images. |
|
222 |
|
223 @pre The parameter aUsage has at least one usage bit set. |
|
224 @pre The number of elements in the array referenced by the parameter |
|
225 aPixelFormats is zero. |
|
226 @param[in] aUsage A combination of usages from TSgUsageBits. |
|
227 @param[out] aPixelFormats A reference to an array that on input must be empty |
|
228 and on return contains the list of supported pixel formats. |
|
229 @param[in] aAttributes A pointer to an array with extension image attributes, |
|
230 if any extension of the Graphics Resource API defines extension image |
|
231 attributes that have an impact on the list of supported pixel formats, |
|
232 or NULL otherwise. |
|
233 @return KErrNone if successful; |
|
234 KErrArgument if either |
|
235 1. the parameter aUsage does not have at least one usage bit set or |
|
236 2. the number of elements in the array referenced by the parameter |
|
237 aPixelFormats was not zero before calling this function; |
|
238 KErrNotSupported if the parameter aAttributes is not NULL and one or |
|
239 more of the extension attributes in the array is not defined by any |
|
240 extension of the Graphics Resource API; |
|
241 KErrNoMemory if there is not enough system memory to add a pixel format |
|
242 to the array referenced by the parameter aPixelFormats. |
|
243 */ |
|
244 IMPORT_C static TInt GetPixelFormats(TUint32 aUsage, |
|
245 RArray<TInt>& aPixelFormats, |
|
246 const TSgAttributeArrayBase* aAttributes = NULL); |
|
247 }; |
|
248 |
|
249 #include <sgresource/sgimage.inl> |
|
250 |
|
251 #endif // SGIMAGE_H |