|
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 // |
|
15 |
|
16 /** |
|
17 @file |
|
18 @publishedPartner |
|
19 @prototype |
|
20 */ |
|
21 |
|
22 #ifndef SGIMAGE_H |
|
23 #define SGIMAGE_H |
|
24 |
|
25 #include <graphics/sgresource.h> |
|
26 #include <pixelformats.h> |
|
27 |
|
28 |
|
29 /** |
|
30 @publishedPartner |
|
31 @prototype |
|
32 @deprecated |
|
33 |
|
34 This class is used to create images and to return information about them. |
|
35 |
|
36 An image is created as constant if the requested CPU access is ESgCpuAccessNone or |
|
37 ESgCpuAccessReadOnly and the requested usage does not include any usage as target. |
|
38 Otherwise it is created as mutable. |
|
39 |
|
40 For an instance of TSgImageInfo to be valid, the following conditions must be true: |
|
41 - The width and height must both be greater than zero. |
|
42 - The screen identifier must be greater than or equal to -1 (-1 is reserved to |
|
43 mean screen-agnostic). |
|
44 - If the usage includes ESgUsageScreenSource then the screen identifier must not |
|
45 be -1. |
|
46 - The number of user-defined attributes must be greater than or equal to zero. |
|
47 - If the number of user-defined attributes is greater than zero then the pointer |
|
48 to the array of user-defined attributes must not be null. |
|
49 |
|
50 For an image creation request to succeed, the following conditions must be true: |
|
51 - The instance of TSgImageInfo passed in as a parameter must be valid. |
|
52 - If the screen identifier is not -1 then it must refer to an existing screen. |
|
53 - If the usage includes ESgUsageScreenSource then the width and height must be |
|
54 compatible with the specified screen. |
|
55 - The pixel format must be compatible with the shareability, CPU access, usage and |
|
56 screen identifier. Compatibility is device-dependent, with the exception that |
|
57 to allow generic applications to exist, some level of compatibility must be |
|
58 guaranteed across all systems. To allow efficient implementation on the widest |
|
59 range of hardware, the number of compatibility guarantees is limited. |
|
60 See Image Compatibility Guarantees for more information. |
|
61 |
|
62 @see RSgImage::GetPixelFormats() |
|
63 @see RSgImage::Create() |
|
64 */ |
|
65 NONSHARABLE_CLASS(TSgImageInfo) |
|
66 { |
|
67 public: |
|
68 IMPORT_C TSgImageInfo(); |
|
69 public: |
|
70 /** |
|
71 The size of the image in pixels. |
|
72 */ |
|
73 TSize iSizeInPixels; |
|
74 /** |
|
75 The pixel format of the image. Note that this value is only guaranteed to be |
|
76 the actual pixel format if the image is mappable. Otherwise it is acceptable |
|
77 for the image to be stored internally in a different format so long as there |
|
78 is no loss of information. In all cases, if the user passes in some initial |
|
79 data to populate the image during creation, this value is assumed to be the |
|
80 exact pixel format of the data passed in. |
|
81 */ |
|
82 TUidPixelFormat iPixelFormat; |
|
83 /** |
|
84 Defines the possible usage of the image in terms of the rendering pipelines, and |
|
85 purposes within those pipelines, that it will be used for. It is interpreted as a |
|
86 combination of the bit flags defined in TSgUsageFlags. An image with limited usage |
|
87 is likely to give higher performance than an image with more general usage. |
|
88 */ |
|
89 TUint32 iUsage; |
|
90 /** |
|
91 Defines whether the image is shareable between processes. A non-shareable image |
|
92 is likely to give higher performance than a shareable image. |
|
93 */ |
|
94 TBool iShareable; |
|
95 /** |
|
96 Defines whether and how the image is mappable for CPU access. An image that is not |
|
97 mappable for CPU access is likely to give higher performance than a mappable image. |
|
98 */ |
|
99 TSgCpuAccess iCpuAccess; |
|
100 /** |
|
101 Defines whether the image is usable on all screens or just on a specific screen. |
|
102 A value of -1 is interpreted as meaning that the image is usable on all screens. |
|
103 Zero and positive values are interpreted as meaning that the image is only |
|
104 valid for use on the specified screen. A screen-specific image is likely to |
|
105 give higher performance than a screen-agnostic image. |
|
106 */ |
|
107 TInt iScreenId; |
|
108 /** |
|
109 In image creation requests, a pointer to an array with the user-defined attributes |
|
110 to be attached to the image or null if the image is to have no user-defined |
|
111 attributes. |
|
112 |
|
113 In information queries, a pointer to an array that on input contains the globally |
|
114 unique identifiers of the user-defined attributes to be retrieved from the image |
|
115 and on return will contain the values of the selected user-defined attributes. |
|
116 If null then the information query will not retrieve any user-defined attributes. |
|
117 */ |
|
118 TSgUserAttribute* iUserAttributes; |
|
119 /** |
|
120 In image creation requests, the number of user-defined attributes to be attached |
|
121 to the image. |
|
122 |
|
123 In information queries, the number of user-defined attributes to be retrieved |
|
124 from the image. |
|
125 */ |
|
126 TInt iUserAttributeCount; |
|
127 }; |
|
128 |
|
129 |
|
130 /** |
|
131 @publishedPartner |
|
132 @prototype |
|
133 @deprecated |
|
134 |
|
135 This globally unique identifier represents both the handle type for instances of |
|
136 RSgImage and the drawable resource type associated with images. |
|
137 */ |
|
138 const TUid KSgImageTypeUid = {0x10285A73}; |
|
139 |
|
140 |
|
141 /** |
|
142 @publishedPartner |
|
143 @prototype |
|
144 @deprecated |
|
145 |
|
146 A handle to a reference-counted, bi-dimensional pixel array that can be used for |
|
147 various purposes, such as being a source or a target of different rendering pipelines, |
|
148 according to its attributes, which are set at creation time and cannot be changed |
|
149 afterwards. |
|
150 |
|
151 An image can be shared between processes by passing its unique identifier across. |
|
152 Alternatively it can be created as not shareable, or process-specific, and this may |
|
153 have performance advantages. Sharing is achieved by using the value returned by Id() |
|
154 in a call to Open() on another instance of RSgImage to open a new handle to the image. |
|
155 Since images are reference-counted they are guaranteed to exist while there are open |
|
156 handles referencing them. |
|
157 |
|
158 An image can be created for use with any screen. Alternatively it can be created as |
|
159 screen-specific and this may have performance advantages. |
|
160 |
|
161 An image can be created as mappable. This means that the CPU can potentially read |
|
162 and/or write directly to the pixel data. It is recommended to use mappable images only |
|
163 when absolutely necessary because they can be less efficient than non-mappable images. |
|
164 |
|
165 An image can be created as constant or mutable. Constant images, also known as immutable |
|
166 images, do not allow modification after creation and this may have performance advantages. |
|
167 A mutable image can be modified after creation, e.g. by using it as a rendering target. |
|
168 A constant image cannot be used as a rendering target. |
|
169 |
|
170 A new RSgImage handle does not refer to an image until a successful call to Create() |
|
171 or Open(). Before that point, the handle is said to be a null handle. Instances of |
|
172 RSgImage can be shared among threads in the same process. |
|
173 |
|
174 An RSgImage handle is said to be invalid if it is not null but it does not reference |
|
175 an existing image. Copying an instance of RSgImage must be done with extreme care, |
|
176 since it does not increment the reference count of the referenced image and may |
|
177 therefore allow some RSgImage handle to become invalid when the image is destroyed. |
|
178 */ |
|
179 NONSHARABLE_CLASS(RSgImage): public RSgDrawable |
|
180 { |
|
181 friend class RSgImageCollection; |
|
182 public: |
|
183 IMPORT_C RSgImage(); |
|
184 IMPORT_C TInt Create(const TSgImageInfo& aInfo, const TAny* aDataAddress, TInt aDataStride); |
|
185 IMPORT_C TInt Create(const TSgImageInfo& aInfo, const RSgImage& aImage); |
|
186 IMPORT_C TInt GetInfo(TSgImageInfo& aInfo) const; |
|
187 IMPORT_C TInt MapReadOnly(const TAny*& aDataAddress, TInt& aDataStride) const; |
|
188 IMPORT_C TInt MapWriteOnly(TAny*& aDataAddress, TInt& aDataStride); |
|
189 IMPORT_C TInt MapReadWrite(TAny*& aDataAddress, TInt& aDataStride); |
|
190 IMPORT_C TInt Unmap() const; |
|
191 IMPORT_C static TInt GetPixelFormats(const TSgImageInfo& aInfo, TUidPixelFormat* aPixelFormats, TInt& aCount); |
|
192 }; |
|
193 |
|
194 |
|
195 #endif // SGIMAGE_H |