1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/graphics/graphicsresourceservices/graphicsresource/inc/sgimage.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,195 @@
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 +//
1.18 +
1.19 +/**
1.20 + @file
1.21 + @publishedPartner
1.22 + @prototype
1.23 +*/
1.24 +
1.25 +#ifndef SGIMAGE_H
1.26 +#define SGIMAGE_H
1.27 +
1.28 +#include <graphics/sgresource.h>
1.29 +#include <pixelformats.h>
1.30 +
1.31 +
1.32 +/**
1.33 +@publishedPartner
1.34 +@prototype
1.35 +@deprecated
1.36 +
1.37 +This class is used to create images and to return information about them.
1.38 +
1.39 +An image is created as constant if the requested CPU access is ESgCpuAccessNone or
1.40 +ESgCpuAccessReadOnly and the requested usage does not include any usage as target.
1.41 +Otherwise it is created as mutable.
1.42 +
1.43 +For an instance of TSgImageInfo to be valid, the following conditions must be true:
1.44 + - The width and height must both be greater than zero.
1.45 + - The screen identifier must be greater than or equal to -1 (-1 is reserved to
1.46 + mean screen-agnostic).
1.47 + - If the usage includes ESgUsageScreenSource then the screen identifier must not
1.48 + be -1.
1.49 + - The number of user-defined attributes must be greater than or equal to zero.
1.50 + - If the number of user-defined attributes is greater than zero then the pointer
1.51 + to the array of user-defined attributes must not be null.
1.52 +
1.53 +For an image creation request to succeed, the following conditions must be true:
1.54 + - The instance of TSgImageInfo passed in as a parameter must be valid.
1.55 + - If the screen identifier is not -1 then it must refer to an existing screen.
1.56 + - If the usage includes ESgUsageScreenSource then the width and height must be
1.57 + compatible with the specified screen.
1.58 + - The pixel format must be compatible with the shareability, CPU access, usage and
1.59 + screen identifier. Compatibility is device-dependent, with the exception that
1.60 + to allow generic applications to exist, some level of compatibility must be
1.61 + guaranteed across all systems. To allow efficient implementation on the widest
1.62 + range of hardware, the number of compatibility guarantees is limited.
1.63 + See Image Compatibility Guarantees for more information.
1.64 +
1.65 +@see RSgImage::GetPixelFormats()
1.66 +@see RSgImage::Create()
1.67 +*/
1.68 +NONSHARABLE_CLASS(TSgImageInfo)
1.69 + {
1.70 +public:
1.71 + IMPORT_C TSgImageInfo();
1.72 +public:
1.73 + /**
1.74 + The size of the image in pixels.
1.75 + */
1.76 + TSize iSizeInPixels;
1.77 + /**
1.78 + The pixel format of the image. Note that this value is only guaranteed to be
1.79 + the actual pixel format if the image is mappable. Otherwise it is acceptable
1.80 + for the image to be stored internally in a different format so long as there
1.81 + is no loss of information. In all cases, if the user passes in some initial
1.82 + data to populate the image during creation, this value is assumed to be the
1.83 + exact pixel format of the data passed in.
1.84 + */
1.85 + TUidPixelFormat iPixelFormat;
1.86 + /**
1.87 + Defines the possible usage of the image in terms of the rendering pipelines, and
1.88 + purposes within those pipelines, that it will be used for. It is interpreted as a
1.89 + combination of the bit flags defined in TSgUsageFlags. An image with limited usage
1.90 + is likely to give higher performance than an image with more general usage.
1.91 + */
1.92 + TUint32 iUsage;
1.93 + /**
1.94 + Defines whether the image is shareable between processes. A non-shareable image
1.95 + is likely to give higher performance than a shareable image.
1.96 + */
1.97 + TBool iShareable;
1.98 + /**
1.99 + Defines whether and how the image is mappable for CPU access. An image that is not
1.100 + mappable for CPU access is likely to give higher performance than a mappable image.
1.101 + */
1.102 + TSgCpuAccess iCpuAccess;
1.103 + /**
1.104 + Defines whether the image is usable on all screens or just on a specific screen.
1.105 + A value of -1 is interpreted as meaning that the image is usable on all screens.
1.106 + Zero and positive values are interpreted as meaning that the image is only
1.107 + valid for use on the specified screen. A screen-specific image is likely to
1.108 + give higher performance than a screen-agnostic image.
1.109 + */
1.110 + TInt iScreenId;
1.111 + /**
1.112 + In image creation requests, a pointer to an array with the user-defined attributes
1.113 + to be attached to the image or null if the image is to have no user-defined
1.114 + attributes.
1.115 +
1.116 + In information queries, a pointer to an array that on input contains the globally
1.117 + unique identifiers of the user-defined attributes to be retrieved from the image
1.118 + and on return will contain the values of the selected user-defined attributes.
1.119 + If null then the information query will not retrieve any user-defined attributes.
1.120 + */
1.121 + TSgUserAttribute* iUserAttributes;
1.122 + /**
1.123 + In image creation requests, the number of user-defined attributes to be attached
1.124 + to the image.
1.125 +
1.126 + In information queries, the number of user-defined attributes to be retrieved
1.127 + from the image.
1.128 + */
1.129 + TInt iUserAttributeCount;
1.130 + };
1.131 +
1.132 +
1.133 +/**
1.134 +@publishedPartner
1.135 +@prototype
1.136 +@deprecated
1.137 +
1.138 +This globally unique identifier represents both the handle type for instances of
1.139 +RSgImage and the drawable resource type associated with images.
1.140 +*/
1.141 +const TUid KSgImageTypeUid = {0x10285A73};
1.142 +
1.143 +
1.144 +/**
1.145 +@publishedPartner
1.146 +@prototype
1.147 +@deprecated
1.148 +
1.149 +A handle to a reference-counted, bi-dimensional pixel array that can be used for
1.150 +various purposes, such as being a source or a target of different rendering pipelines,
1.151 +according to its attributes, which are set at creation time and cannot be changed
1.152 +afterwards.
1.153 +
1.154 +An image can be shared between processes by passing its unique identifier across.
1.155 +Alternatively it can be created as not shareable, or process-specific, and this may
1.156 +have performance advantages. Sharing is achieved by using the value returned by Id()
1.157 +in a call to Open() on another instance of RSgImage to open a new handle to the image.
1.158 +Since images are reference-counted they are guaranteed to exist while there are open
1.159 +handles referencing them.
1.160 +
1.161 +An image can be created for use with any screen. Alternatively it can be created as
1.162 +screen-specific and this may have performance advantages.
1.163 +
1.164 +An image can be created as mappable. This means that the CPU can potentially read
1.165 +and/or write directly to the pixel data. It is recommended to use mappable images only
1.166 +when absolutely necessary because they can be less efficient than non-mappable images.
1.167 +
1.168 +An image can be created as constant or mutable. Constant images, also known as immutable
1.169 +images, do not allow modification after creation and this may have performance advantages.
1.170 +A mutable image can be modified after creation, e.g. by using it as a rendering target.
1.171 +A constant image cannot be used as a rendering target.
1.172 +
1.173 +A new RSgImage handle does not refer to an image until a successful call to Create()
1.174 +or Open(). Before that point, the handle is said to be a null handle. Instances of
1.175 +RSgImage can be shared among threads in the same process.
1.176 +
1.177 +An RSgImage handle is said to be invalid if it is not null but it does not reference
1.178 +an existing image. Copying an instance of RSgImage must be done with extreme care,
1.179 +since it does not increment the reference count of the referenced image and may
1.180 +therefore allow some RSgImage handle to become invalid when the image is destroyed.
1.181 +*/
1.182 +NONSHARABLE_CLASS(RSgImage): public RSgDrawable
1.183 + {
1.184 + friend class RSgImageCollection;
1.185 +public:
1.186 + IMPORT_C RSgImage();
1.187 + IMPORT_C TInt Create(const TSgImageInfo& aInfo, const TAny* aDataAddress, TInt aDataStride);
1.188 + IMPORT_C TInt Create(const TSgImageInfo& aInfo, const RSgImage& aImage);
1.189 + IMPORT_C TInt GetInfo(TSgImageInfo& aInfo) const;
1.190 + IMPORT_C TInt MapReadOnly(const TAny*& aDataAddress, TInt& aDataStride) const;
1.191 + IMPORT_C TInt MapWriteOnly(TAny*& aDataAddress, TInt& aDataStride);
1.192 + IMPORT_C TInt MapReadWrite(TAny*& aDataAddress, TInt& aDataStride);
1.193 + IMPORT_C TInt Unmap() const;
1.194 + IMPORT_C static TInt GetPixelFormats(const TSgImageInfo& aInfo, TUidPixelFormat* aPixelFormats, TInt& aCount);
1.195 + };
1.196 +
1.197 +
1.198 +#endif // SGIMAGE_H