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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
25 #include <graphics/sgresource.h>
26 #include <pixelformats.h>
34 This class is used to create images and to return information about them.
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.
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
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.
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.
62 @see RSgImage::GetPixelFormats()
63 @see RSgImage::Create()
65 NONSHARABLE_CLASS(TSgImageInfo)
68 IMPORT_C TSgImageInfo();
71 The size of the image in pixels.
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.
82 TUidPixelFormat iPixelFormat;
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.
91 Defines whether the image is shareable between processes. A non-shareable image
92 is likely to give higher performance than a shareable image.
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.
99 TSgCpuAccess iCpuAccess;
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.
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
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.
118 TSgUserAttribute* iUserAttributes;
120 In image creation requests, the number of user-defined attributes to be attached
123 In information queries, the number of user-defined attributes to be retrieved
126 TInt iUserAttributeCount;
135 This globally unique identifier represents both the handle type for instances of
136 RSgImage and the drawable resource type associated with images.
138 const TUid KSgImageTypeUid = {0x10285A73};
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
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.
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.
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.
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.
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.
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.
179 NONSHARABLE_CLASS(RSgImage): public RSgDrawable
181 friend class RSgImageCollection;
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);