os/graphics/windowing/windowserver/inc/Graphics/openwfc/surfaceconfiguration.inl
changeset 0 bde4ae8d615e
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/os/graphics/windowing/windowserver/inc/Graphics/openwfc/surfaceconfiguration.inl	Fri Jun 15 03:10:57 2012 +0200
     1.3 @@ -0,0 +1,432 @@
     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 +// Sets all members to default values. Initializes the size field to match the object size.
    1.18 +// 
    1.19 +//
    1.20 +/**
    1.21 +@file
    1.22 +@publishedpartner 
    1.23 +@released
    1.24 +*/
    1.25 +
    1.26 +inline TSurfaceConfiguration::TSurfaceConfiguration()
    1.27 +	{}
    1.28 +
    1.29 +/**
    1.30 +Copy constructor. This constructor will read the size field of the source and target 
    1.31 +objects and only copy the minimum set of fields indicated. Any remaining fields in the target 
    1.32 +object will be set to default values. 
    1.33 +
    1.34 +@param aSurfaceConfiguration Config to copy
    1.35 +*/
    1.36 +inline TSurfaceConfiguration::TSurfaceConfiguration(const TSurfaceConfiguration& aSurfaceConfiguration):
    1.37 +	TSurfaceConfiguration2(0)
    1.38 +	{
    1.39 +	TInt tempSize = aSurfaceConfiguration.Size();
    1.40 +	if (tempSize > sizeof(*this))
    1.41 +		{
    1.42 +		tempSize = sizeof(*this);
    1.43 +		}
    1.44 +	Mem::Copy(this, &aSurfaceConfiguration, tempSize);
    1.45 +	iSize = tempSize;
    1.46 +	}
    1.47 +
    1.48 +/**
    1.49 +This constructor will take any value, but it is designed to be used with
    1.50 +a value returned by RWsSession::PreferredSurfaceConfigurationSize, 
    1.51 +and initializes the members to represent an object compatible with that.
    1.52 +
    1.53 +If the aPreferredMaxSize is larger than the actual size of TSurfaceConfiguration, indicating 
    1.54 +that the server supports a newer version of the interface than the caller is aware of, then 
    1.55 +the actual size is used.
    1.56 +
    1.57 +If the aPreferredMaxSize is smaller than the actual size of TSurfaceConfiguration, indicating 
    1.58 +that the server supports an earlier version of the interface, then this value is used. It must 
    1.59 +match the Size() member of one of the defined hierarchy of TSurfaceConfiguration classes.
    1.60 +
    1.61 +@param aPreferredMaxSize User defined max size
    1.62 +@see RWsSession::PreferredSurfaceConfigurationSize
    1.63 +*/
    1.64 +inline TSurfaceConfiguration::TSurfaceConfiguration(TInt aPreferredMaxSize):
    1.65 +	TSurfaceConfiguration2(sizeof(*this))
    1.66 +	{
    1.67 +	if (sizeof(*this) > aPreferredMaxSize)
    1.68 +		{
    1.69 +		iSize = aPreferredMaxSize;
    1.70 +		}
    1.71 +	}
    1.72 +
    1.73 +/** Default constructor for configuration 1
    1.74 +*/
    1.75 +inline TSurfaceConfiguration1::TSurfaceConfiguration1():TSurfaceConfigurationSize(sizeof(*this))
    1.76 +		,iExtent(TRect::EUninitialized), iViewport(TRect::EUninitialized)
    1.77 +	{}
    1.78 +
    1.79 +/**
    1.80 +Constructor for configuration 1 passing through a size already calculated
    1.81 +
    1.82 +@param aSize Size of the class already calculated and being passed up through the classes
    1.83 +*/
    1.84 +inline TSurfaceConfiguration1::TSurfaceConfiguration1(TInt aSize):TSurfaceConfigurationSize(aSize)
    1.85 +		,iExtent(TRect::EUninitialized), iViewport(TRect::EUninitialized)
    1.86 +	{}
    1.87 +
    1.88 +/**
    1.89 +The method sets the surface ID to be set as the background surface. 
    1.90 +
    1.91 +The default initial value held in this class for surface ID is the null surface ID.
    1.92 +
    1.93 +Note that SetBackgroundSurface() will not accept a null surface ID, so this parameter must always be set.
    1.94 +
    1.95 +@param aSurfaceId Surface ID to set
    1.96 +@return KErrNone on success or a system-wide error code
    1.97 +	- KErrNotSupported if not supported.
    1.98 +@post The Surface Id values are updated in the object of this class if supported. The 
    1.99 +SetBackgroundSurface API must be called passing object of this class as parameter to 
   1.100 +get the desired effect.
   1.101 +*/
   1.102 +inline TInt TSurfaceConfiguration1::SetSurfaceId (const TSurfaceId& aSurfaceId)
   1.103 +	{
   1.104 +	if (MemberAccessible(iSurfaceId))
   1.105 +		{
   1.106 +		iSurfaceId = aSurfaceId;
   1.107 +		return KErrNone;
   1.108 +		}	
   1.109 +	return KErrNotSupported;
   1.110 +	}
   1.111 +
   1.112 +/**
   1.113 +The method gets the surface ID stored in the object of this class.
   1.114 +
   1.115 +@param aSurfaceId User surface id to be set
   1.116 +@post The aSurface parameter is filled in.
   1.117 +@post If the instance of TSurfaceConfiguration is too small, the null surface ID will be set.
   1.118 +*/
   1.119 +inline void TSurfaceConfiguration1::GetSurfaceId (TSurfaceId& aSurfaceId) const
   1.120 +	{
   1.121 +	if (MemberAccessible(iSurfaceId))
   1.122 +		{
   1.123 +		aSurfaceId = iSurfaceId;
   1.124 +		}
   1.125 +	else
   1.126 +		{
   1.127 +		aSurfaceId.CreateNullId();
   1.128 +		}
   1.129 +	}
   1.130 +
   1.131 +/**
   1.132 +The method sets the area of the surface that should be mapped to the specified window area. 
   1.133 +The viewport is in surface coordinates.
   1.134 +
   1.135 +In SetBackgroundSurface(), if not set or if the set viewport is empty, the size of the whole surface 
   1.136 +is used as the viewport. If the surface is changed then the viewport will track the size of 
   1.137 +the surface. 
   1.138 +
   1.139 +Setting any ordinate of the viewport outside the surface size is not required specified behavior for 
   1.140 +this interface. The call will not fail if any ordinates are out of range, and the internal NGA Composition 
   1.141 +handling of this case will produce a representative image. This current behavior is that the NGA Composition 
   1.142 +will clamp any out-of-range ordinate to the size of the surface.
   1.143 +
   1.144 +@param aViewport A rectangle of the area, in relative coordinates to the surface
   1.145 +@return KErrNone on success or a system-wide error code
   1.146 +	- KErrNotSupported if not supported.
   1.147 +@post The viewport values are updated in the object of this class. This does not imply that the 
   1.148 +viewport is set for the surface. The SetBackgroundSurface API must be called passing an object of 
   1.149 +this class as parameter to get the desired effect.
   1.150 +*/
   1.151 +inline TInt TSurfaceConfiguration1::SetViewport (const TRect& aViewport)
   1.152 +	{
   1.153 +	if (MemberAccessible(iViewport))
   1.154 +		{
   1.155 +		iViewport = aViewport;
   1.156 +		return KErrNone;
   1.157 +		}
   1.158 +	return KErrNotSupported;
   1.159 +	}
   1.160 +
   1.161 +/**
   1.162 +This method gets the viewport stored in the object of this class. The viewport is in surface 
   1.163 +coordinates.
   1.164 +
   1.165 +If viewport was not set or an empty viewport was set, the value returned is an empty viewport. This 
   1.166 +is an indication that the viewport used by the server is equal to the size of the surface. The 
   1.167 +actual size of the surface is not returned.
   1.168 +
   1.169 +@param aViewport User viewport to be set.
   1.170 +@post The aViewport rectangle is filled in.
   1.171 +@post If the instance of TSurfaceConfiguration is too small, the empty viewport rectangle will be returned.
   1.172 +*/
   1.173 +inline void TSurfaceConfiguration1::GetViewport (TRect& aViewport) const
   1.174 +	{
   1.175 +	if (MemberAccessible(iViewport))
   1.176 +		{
   1.177 +		aViewport = iViewport;
   1.178 +		}
   1.179 +	else
   1.180 +		{
   1.181 +		aViewport = TRect();
   1.182 +		}
   1.183 +	}
   1.184 +
   1.185 +/**
   1.186 +This method sets the relative orientation of viewport to window extent. The default value is 
   1.187 +EGraphicsOrientationNormal.
   1.188 +
   1.189 +The rotation effect is applied to the input viewport area, around the centre-point of the viewport.
   1.190 +
   1.191 +@param aOrientation User orientation to be set
   1.192 +@return KErrNone on success or a system-wide error code
   1.193 +	- KErrNotSupported if not supported.
   1.194 +	- KErrArgument if aOrientation is out of range
   1.195 +@post The orientation is updated in the object of this class. This does not imply that the orientation 
   1.196 +is set for the surface content. The SetBackgroundSurface API must be called passing an object of 
   1.197 +this class as parameter to get the desired effect.
   1.198 +*/
   1.199 +inline TInt TSurfaceConfiguration1::SetOrientation (CFbsBitGc::TGraphicsOrientation aOrientation)
   1.200 +	{
   1.201 +	if (MemberAccessible(iOrientation))
   1.202 +		{
   1.203 +		__ASSERT_COMPILE(CFbsBitGc::EGraphicsOrientationNormal==0 && 
   1.204 +						CFbsBitGc::EGraphicsOrientationRotated270 == 3);
   1.205 +		if(aOrientation < CFbsBitGc::EGraphicsOrientationNormal || 
   1.206 +				aOrientation > CFbsBitGc::EGraphicsOrientationRotated270)
   1.207 +			{
   1.208 +			return KErrArgument;
   1.209 +			}
   1.210 +		iOrientation = aOrientation;
   1.211 +		return KErrNone;
   1.212 +		}
   1.213 +	return KErrNotSupported;
   1.214 +	}
   1.215 +
   1.216 +/**
   1.217 +The method gets the surface orientation angle stored in the object of this class. It is the 
   1.218 +relative orientation of viewport to window extent. If orientation was not set, the value returned 
   1.219 +will be EGraphicsOrientationNormal.
   1.220 +
   1.221 +@return orientation in this object
   1.222 +@post If the instance of TSurfaceConfiguration is too small, the default EGraphicsOrientationNormal 
   1.223 +setting will be returned.
   1.224 +*/
   1.225 +inline CFbsBitGc::TGraphicsOrientation TSurfaceConfiguration1::Orientation() const
   1.226 +	{
   1.227 +	if (MemberAccessible(iOrientation))
   1.228 +		{
   1.229 +		return iOrientation;
   1.230 +		}
   1.231 +	else
   1.232 +		{
   1.233 +		return CFbsBitGc::EGraphicsOrientationNormal;
   1.234 +		}
   1.235 +	}
   1.236 +
   1.237 +/**
   1.238 +This method sets the area of the window where the surface content is to be placed. The extent is 
   1.239 +in window coordinates.
   1.240 +
   1.241 +If not set or if the set extent is empty, the size of the entire window is used as the default extent. 
   1.242 +The default extent changes according to the change in the window size. The empty extent is an indication 
   1.243 +to the server that the extent should fill the entire window without the client tracking the change in 
   1.244 +the window size.
   1.245 +
   1.246 +In SetBackgroundSurface() it is legal to set the extent larger than the window, or the window may 
   1.247 +become smaller than the extent. In these cases the output will be transformed on the basis of this 
   1.248 +larger extent, but then clipped to the window outline.
   1.249 +
   1.250 +@param aExtent Area on the window where the surface contents specified by viewport
   1.251 +should be mapped
   1.252 +@return KErrNone on success or a system-wide error code
   1.253 +	- KErrNotSupported if not supported.
   1.254 +@post The extent values are updated in the object of this class. This does not imply that the 
   1.255 +extent is set for the surface. The SetBackgroundSurface API must be called passing an object of 
   1.256 +this class as parameter to get the desired effect.
   1.257 +*/
   1.258 +inline TInt TSurfaceConfiguration1::SetExtent(const TRect& aExtent)
   1.259 +	{
   1.260 +	if (MemberAccessible(iExtent))
   1.261 +		{
   1.262 +		iExtent = aExtent;
   1.263 +		return KErrNone;
   1.264 +		}
   1.265 +	return KErrNotSupported;
   1.266 +	}
   1.267 +
   1.268 +/**
   1.269 +The method gets the extent stored in the object of this class. The extent is in window coordinates.
   1.270 +
   1.271 +If extent was not set or an empty extent was set, the value returned will be an empty extent. This 
   1.272 +is an indication that the extent used by the server is equal to the size of the window. The actual 
   1.273 +size of the window is not returned.
   1.274 +
   1.275 +@param aExtent User extent to be set
   1.276 +@post The aExtent parameter is filled in
   1.277 +@post If the instance of TSurfaceConfiguration is too small, the empty extent rectangle will be returned.
   1.278 +*/
   1.279 +inline void TSurfaceConfiguration1::GetExtent(TRect& aExtent) const
   1.280 +	{
   1.281 +	if (MemberAccessible(iExtent))
   1.282 +		{
   1.283 +		aExtent = iExtent;
   1.284 +		}
   1.285 +	else
   1.286 +		{
   1.287 +		aExtent = TRect();
   1.288 +		}
   1.289 +	}
   1.290 +
   1.291 +/**
   1.292 +This method identifies which attributes are available to use.
   1.293 +
   1.294 +Generally, any version of the server will accept any version of TSurfaceConfiguration, ignoring 
   1.295 +newer version attributes it does not recognize and substituting defaults for attributes not present 
   1.296 +in older version.
   1.297 +
   1.298 +However, by using this method in conjunction with GetBackgroundSurface() the intelligent client can 
   1.299 +identify which blocks of attributes are actually present and supported after a call to 
   1.300 +GetBackgroundSurface, avoiding preparing complex attributes, or reducing user-interface control 
   1.301 +gadgets.
   1.302 +
   1.303 +@return ETrue if all these attributes are available to use; otherwise EFalse
   1.304 +*/
   1.305 +inline TBool TSurfaceConfiguration1::SupportsAllMembers()
   1.306 +	{
   1.307 +	if (Size() >= sizeof(*this))
   1.308 +		{
   1.309 +		return ETrue;
   1.310 +		}
   1.311 +	else
   1.312 +		{
   1.313 +		return EFalse;
   1.314 +		}
   1.315 +	}
   1.316 +
   1.317 +/**
   1.318 +Constructs the TSurfaceConfigurationSize class, enters the size field and blanks everything else
   1.319 +
   1.320 +@param aSize The size to set for the configuration
   1.321 +@return ETrue If all these attributes are available to use; otherwise EFalse
   1.322 +*/
   1.323 +inline TSurfaceConfigurationSize::TSurfaceConfigurationSize(TInt aSize)
   1.324 +	{
   1.325 +	Mem::FillZ(this,aSize);
   1.326 +	iSize = aSize;
   1.327 +	}
   1.328 +
   1.329 +/**
   1.330 +Reads the size field. The size is set automatically in the constructor, or by the 
   1.331 +GetBackgroundSurface method to indicate the sender’s supported structure size, and imply a 
   1.332 +compatible version identifier. The size reported after GetBackgroundSurface will match 
   1.333 +the expected size of one of the hierarchy of TSurfaceConfiguration classes documented in the 
   1.334 +header, and will never exceed the constructed size.
   1.335 +
   1.336 +@return ETrue if all these attributes are available to use; otherwise EFalse
   1.337 +*/
   1.338 +inline TInt TSurfaceConfigurationSize::Size() const
   1.339 +	{
   1.340 +	return iSize;
   1.341 +	}
   1.342 +
   1.343 +inline TBool TSurfaceConfigurationSize::operator == (const TSurfaceConfigurationSize& aRhs)const
   1.344 +	{
   1.345 +	return aRhs.Size()==Size();	//If the two objects are not the same version then we can't compare them!
   1.346 +	}
   1.347 +inline TBool TSurfaceConfiguration1::operator == (const TSurfaceConfiguration1& aRhs)const
   1.348 +	{
   1.349 +	if (!TSurfaceConfigurationSize::operator ==(aRhs))
   1.350 +		return EFalse;	//Check for earlier version compatability
   1.351 +	if (Size()<sizeof(*this))
   1.352 +		return ETrue;	//If the objects are smaller than this then the check is complete
   1.353 +	return 	(iSurfaceId==aRhs.iSurfaceId)
   1.354 +		&&	(iOrientation==aRhs.iOrientation)
   1.355 +		&&	(iExtent==aRhs.iExtent)
   1.356 +		&&	(iViewport==aRhs.iViewport)
   1.357 +		;
   1.358 +	}
   1.359 +
   1.360 +/** Default constructor for configuration 2
   1.361 +*/
   1.362 +inline TSurfaceConfiguration2::TSurfaceConfiguration2():TSurfaceConfiguration1(sizeof(*this))
   1.363 +        ,iFlip(EFalse)
   1.364 +    {}
   1.365 +
   1.366 +/**
   1.367 +Constructor for configuration 2 passing through a size already calculated
   1.368 +
   1.369 +@param aSize Size of the class already calculated and being passed up through the classes
   1.370 +*/
   1.371 +inline TSurfaceConfiguration2::TSurfaceConfiguration2(TInt aSize):TSurfaceConfiguration1(aSize)
   1.372 +        ,iFlip(EFalse)
   1.373 +    {}
   1.374 +
   1.375 +/**
   1.376 +This method sets the flip attribute to the surface. The default value is 
   1.377 +EFalse.
   1.378 +
   1.379 +@param aFlip When ETrue enalbes flip in the x-axis
   1.380 +@post The flip attribute is updated in the object of this class. This does not imply that the flip 
   1.381 +is set for the surface content. The SetBackgroundSurface API must be called passing an object of 
   1.382 +this class as parameter to get the desired effect.
   1.383 +@return KErrNone on success 
   1.384 +    - KErrNotSupported if flip is not supported. 
   1.385 +*/
   1.386 +inline TInt TSurfaceConfiguration2::SetFlip(TBool aFlip)
   1.387 +    {
   1.388 +    if (MemberAccessible(iFlip))
   1.389 +        {
   1.390 +        iFlip = aFlip;
   1.391 +        return KErrNone;
   1.392 +        }
   1.393 +     return KErrNotSupported;
   1.394 +    }
   1.395 +
   1.396 +/**
   1.397 +The method gets the flip attribute of the surface stored in the object of this class. If the flip was not set, the value returned 
   1.398 +will be EFalse.
   1.399 +
   1.400 +@return ETrue if flip is enabled
   1.401 +@post If the instance of TSurfaceConfiguration is too small, the default EFalse 
   1.402 +setting will be returned.
   1.403 +*/
   1.404 +inline TBool TSurfaceConfiguration2::Flip() const
   1.405 +    {
   1.406 +    if (MemberAccessible(iFlip))
   1.407 +        {
   1.408 +        return iFlip;
   1.409 +        }
   1.410 +    else
   1.411 +        {
   1.412 +        return EFalse;
   1.413 +        }
   1.414 +    }
   1.415 +
   1.416 +inline TBool TSurfaceConfiguration2::SupportsAllMembers()
   1.417 +    {
   1.418 +    if (Size() >= sizeof(*this))
   1.419 +        {
   1.420 +        return ETrue;
   1.421 +        }
   1.422 +    else
   1.423 +        {
   1.424 +        return EFalse;
   1.425 +        }
   1.426 +    }
   1.427 +
   1.428 +inline TBool TSurfaceConfiguration2::operator == (const TSurfaceConfiguration2& aRhs)const
   1.429 +    {
   1.430 +    if (!TSurfaceConfiguration1::operator ==(aRhs))
   1.431 +        return EFalse;  //Check for earlier version compatability
   1.432 +    if (Size()<sizeof(*this))
   1.433 +        return ETrue;   //If the objects are smaller than this then the check is complete
   1.434 +    return  iFlip==aRhs.iFlip;
   1.435 +    }