sl@0: // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: //
sl@0: 
sl@0: #include "sgdriver.h"
sl@0: #include "sgimageadapter.h"
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype
sl@0: @deprecated
sl@0: 
sl@0: Default constructor.
sl@0: 
sl@0: @pre None.
sl@0: @post All the data members of this instance of TSgImageInfo are zero, false or null.
sl@0: */
sl@0: EXPORT_C TSgImageInfo::TSgImageInfo()
sl@0: 	{
sl@0: 	Mem::FillZ(this, sizeof(TSgImageInfo));
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype
sl@0: @deprecated
sl@0: 
sl@0: Default constructor.
sl@0: 
sl@0: @pre None.
sl@0: @post This RSgImage handle is null.
sl@0: */
sl@0: EXPORT_C RSgImage::RSgImage()
sl@0: 	{
sl@0: 	iHandleType = KSgImageTypeUid;
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype
sl@0: @deprecated
sl@0: 
sl@0: Creates an image with the specified attributes and, optionally, the specified
sl@0: initial contents.
sl@0: 
sl@0: @param aInfo The attributes of the image to be created.
sl@0: @param aDataAddress The base address of the pixel data used to populate the new image.
sl@0:        If this value is null, the initial contents of the image are undefined.
sl@0:        If aInfo specifies that the new image is constant, this value must not be null.
sl@0: @param aDataStride The number of bytes between rows of the pixel data used to populate
sl@0:        the new image.
sl@0: @pre The Graphics Resource driver is initialised for use in the context of the
sl@0:      calling process.
sl@0: @pre This RSgImage handle is null.
sl@0: @pre aInfo is supported.
sl@0: @post This RSgImage handle references a newly created image with the specified
sl@0:       attributes and initial contents. The initial reference count for the image
sl@0:       is one.
sl@0: @return KErrNone if successful.
sl@0: @return KErrInUse if this RSgImage handle was not null.
sl@0: @return KErrArgument if aInfo is invalid.
sl@0: @return KErrNoInitializationData if aInfo requests a constant image and aDataAddress
sl@0:         is null.
sl@0: @return KErrTooBig if the size specified in aInfo is too large.
sl@0: @return KErrNotSupported if aInfo is not supported.
sl@0: @return KErrNoMemory if there is not enough system memory.
sl@0: @return KErrNoSpecializedMemory if there is not enough specialised graphics memory.
sl@0: @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
sl@0:        for use in the context of the calling process.
sl@0: */
sl@0: EXPORT_C TInt RSgImage::Create(const TSgImageInfo& aInfo, const TAny* aDataAddress, TInt aDataStride)
sl@0: 	{
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Wait();
sl@0: 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
sl@0: #endif
sl@0: 	TInt err = gPls.iDriver->CreateImage(aInfo, aDataAddress, aDataStride, iImpl);
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Signal();
sl@0: #endif
sl@0: 	return err;
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype
sl@0: @deprecated
sl@0: 
sl@0: Creates an image with the specified attributes and initial contents copied from an
sl@0: existing image. The size and the pixel format of the image to be created must be the
sl@0: same as the size and the pixel format of the existing image.
sl@0: 
sl@0: @param aInfo The attributes of the image to be created.
sl@0: @param aImage A handle to the existing image to be copied.
sl@0: @pre The Graphics Resource driver is initialised for use in the context of the
sl@0:      calling process.
sl@0: @pre This RSgImage handle is null.
sl@0: @pre aInfo is supported.
sl@0: @pre aImage is a valid and not null handle.
sl@0: @pre The size and the pixel format specified in aInfo must be the same as the size
sl@0:      and the pixel format of aImage.
sl@0: @post This RSgImage handle references a newly created image with the specified
sl@0:       attributes and initial contents. The initial reference count for the image
sl@0:       is one.
sl@0: @return KErrNone if successful.
sl@0: @return KErrInUse if this RSgImage handle was not null.
sl@0: @return KErrArgument if aInfo is invalid or if aImage is a null handle.
sl@0: @return KErrNotSupported if aInfo is not supported or if the size and the pixel format
sl@0:         specified in aInfo are not the same as the size and the pixel format of aImage.
sl@0: @return KErrNoMemory if there is not enough system memory.
sl@0: @return KErrNoSpecializedMemory if there is not enough specialised graphics memory.
sl@0: @panic SGRES 3 in debug builds if aImage is an invalid handle.
sl@0: @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
sl@0:        for use in the context of the calling process.
sl@0: */
sl@0: EXPORT_C TInt RSgImage::Create(const TSgImageInfo& aInfo, const RSgImage& aImage)
sl@0: 	{
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Wait();
sl@0: 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
sl@0: #endif
sl@0: 	TInt err = gPls.iDriver->CreateImage(aInfo, static_cast<MSgImageAdapter*>(aImage.iImpl), iImpl);
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Signal();
sl@0: #endif
sl@0: 	return err;
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype
sl@0: @deprecated
sl@0: 
sl@0: Retrieves the values of the attributes of an image. This function can also retrieve
sl@0: the values of selected user-defined attributes attached to an image by passing in
sl@0: the globally unique identifiers of the user-defined attributes to be retrieved.
sl@0: 
sl@0: @param aInfo On input, the globally unique identifiers of the user-defined attributes
sl@0:        to be retrieved from the image, if any. On return, the values of the attributes
sl@0:        of the image and the values of the selected user-defined attributes.
sl@0: @pre The Graphics Resource driver is initialised for use in the context of the
sl@0:      calling process.
sl@0: @pre This RSgImage handle is valid and not null.
sl@0: @pre If aInfo.iUserAttributes is not null then it points to an array of
sl@0:      aInfo.iUserAttributeCount elements with globally unique identifiers
sl@0:      corresponding to user-defined attributes attached to the image.
sl@0: @post None.
sl@0: @return KErrNone if successful.
sl@0: @return KErrBadHandle if this RSgImage handle is null.
sl@0: @return KErrNotFound if any of the user-defined attributes to be retrieved from the
sl@0:         image cannot be found.
sl@0: @panic SGRES 3 in debug builds if this RSgImage handle is invalid.
sl@0: @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
sl@0:        for use in the context of the calling process.
sl@0: @see TSgImageInfo
sl@0: */
sl@0: EXPORT_C TInt RSgImage::GetInfo(TSgImageInfo& aInfo) const
sl@0: 	{
sl@0: 	if (!iImpl)
sl@0: 		{
sl@0: 		return KErrBadHandle;
sl@0: 		}
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Wait();
sl@0: 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
sl@0: 	__ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
sl@0: #endif
sl@0: 	TInt err = static_cast<MSgImageAdapter*>(iImpl)->GetInfo(aInfo);
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Signal();
sl@0: #endif
sl@0: 	return err;
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype
sl@0: @deprecated
sl@0: 
sl@0: Temporarily makes the pixel data of an image accessible for reading by the CPU.
sl@0: Undefined behaviour occurs if the CPU tries to modify the pixel data.
sl@0: 
sl@0: When finished with the pixel data, the caller must end the mapping by calling Unmap()
sl@0: on this RSgImage handle.
sl@0: 
sl@0: If an image is shared across processes, only the creator process is allowed to map
sl@0: the image for access to its pixel data.
sl@0: 
sl@0: Depending upon the hardware architecture, whilst an image is mapped the GPU may be
sl@0: denied access to the pixel data, so this function may cause GPU operations that use
sl@0: this image to fail if proper synchronisation is not provided by means of the
sl@0: mechanisms available from the different rendering pipelines or from specialised
sl@0: synchronisation objects. Likewise, if the GPU is using the image at the time this
sl@0: function is called, the mapping may fail with KErrInUse. Note that even if operations
sl@0: do not fail, the results are not guaranteed to be correct unless proper synchronisation
sl@0: is provided.
sl@0: 
sl@0: @param aDataAddress On return, the base address of the pixel data in the address
sl@0:        space of the calling process.
sl@0: @param aDataStride On return, the number of bytes between rows of the pixel data.
sl@0: @pre The Graphics Resource driver is initialised for use in the context of the
sl@0:      calling process.
sl@0: @pre This RSgImage handle is valid and not null.
sl@0: @pre The image is not mapped yet.
sl@0: @pre The image was created with CPU access ESgCpuAccessReadOnly or ESgCpuAccessReadWrite.
sl@0: @pre The image was created by the calling process.
sl@0: @post The pixel data of the image is directly accessible in the address space of the
sl@0:       calling process for reading only, until Unmap() is called.
sl@0: @return KErrNone if successful.
sl@0: @return KErrBadHandle if this RSgImage handle is null.
sl@0: @return KErrInUse if the image is already mapped or in exclusive use by the GPU.
sl@0: @return KErrAccessDenied if the image was not created with CPU access ESgCpuAccessReadOnly
sl@0:         or ESgCpuAccessReadWrite.
sl@0: @return KErrPermissionDenied if the image was created by another process.
sl@0: @return KErrNoMemory if there is not enough system memory.
sl@0: @panic SGRES 3 in debug builds if this RSgImage handle is invalid.
sl@0: @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
sl@0:        for use in the context of the calling process.
sl@0: */
sl@0: EXPORT_C TInt RSgImage::MapReadOnly(const TAny*& aDataAddress, TInt& aDataStride) const
sl@0: 	{
sl@0: 	if (!iImpl)
sl@0: 		{
sl@0: 		return KErrBadHandle;
sl@0: 		}
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Wait();
sl@0: 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
sl@0: 	__ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
sl@0: #endif
sl@0: 	TInt err = static_cast<MSgImageAdapter*>(iImpl)->MapReadOnly(aDataAddress, aDataStride);
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Signal();
sl@0: #endif
sl@0: 	return err;
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype
sl@0: @deprecated
sl@0: 
sl@0: Temporarily makes the pixel data of an image accessible for writing by the CPU.
sl@0: Any pre-existing content is discarded, meaning that the mapped memory initially
sl@0: contains undefined pixel data.
sl@0: 
sl@0: When finished with the pixel data, the caller must end the mapping by calling Unmap()
sl@0: on this RSgImage handle. The caller is required to write to every pixel of the image
sl@0: before unmapping.
sl@0: 
sl@0: If an image is shared across processes, only the creator process is allowed to map
sl@0: the image for access to its pixel data.
sl@0: 
sl@0: Depending upon the hardware architecture, whilst an image is mapped the GPU may be
sl@0: denied access to the pixel data, so this function may cause GPU operations that use
sl@0: this image to fail if proper synchronisation is not provided by means of the
sl@0: mechanisms available from the different rendering pipelines or from specialised
sl@0: synchronisation objects. Likewise, if the GPU is using the image at the time this
sl@0: function is called, the mapping may fail with KErrInUse. Note that even if operations
sl@0: do not fail, the results are not guaranteed to be correct unless proper synchronisation
sl@0: is provided.
sl@0: 
sl@0: @param aDataAddress On return, the base address of the pixel data in the address
sl@0:        space of the calling process.
sl@0: @param aDataStride On return, the number of bytes between rows of the pixel data.
sl@0: @pre The Graphics Resource driver is initialised for use in the context of the
sl@0:      calling process.
sl@0: @pre This RSgImage handle is valid and not null.
sl@0: @pre The image is not mapped yet.
sl@0: @pre The image was created with CPU access ESgCpuAccessWriteOnly or ESgCpuAccessReadWrite.
sl@0: @pre The image was created by the calling process.
sl@0: @post The pixel data of the image is directly accessible in the address space of the
sl@0:       calling process for writing only, until Unmap() is called.
sl@0: @return KErrNone if successful.
sl@0: @return KErrBadHandle if this RSgImage handle is null.
sl@0: @return KErrInUse if the image is already mapped or in exclusive use by the GPU.
sl@0: @return KErrAccessDenied if the image was not created with CPU access ESgCpuAccessWriteOnly
sl@0:         or ESgCpuAccessReadWrite.
sl@0: @return KErrPermissionDenied if the image was created by another process.
sl@0: @return KErrNoMemory if there is not enough system memory.
sl@0: @panic SGRES 3 in debug builds if this RSgImage handle is invalid.
sl@0: @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
sl@0:        for use in the context of the calling process.
sl@0: */
sl@0: EXPORT_C TInt RSgImage::MapWriteOnly(TAny*& aDataAddress, TInt& aDataStride)
sl@0: 	{
sl@0: 	if (!iImpl)
sl@0: 		{
sl@0: 		return KErrBadHandle;
sl@0: 		}
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Wait();
sl@0: 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
sl@0: 	__ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
sl@0: #endif
sl@0: 	TInt err = static_cast<MSgImageAdapter*>(iImpl)->MapWriteOnly(aDataAddress, aDataStride);
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Signal();
sl@0: #endif
sl@0: 	return err;
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype
sl@0: @deprecated
sl@0: 
sl@0: Temporarily makes the pixel data of an image accessible for reading and writing
sl@0: by the CPU.
sl@0: 
sl@0: When finished with the pixel data, the caller must end the mapping by calling Unmap()
sl@0: on this RSgImage handle. Any modification performed by the CPU will be retained upon
sl@0: unmapping.
sl@0: 
sl@0: If an image is shared across processes, only the creator process is allowed to map
sl@0: the image for access to its pixel data.
sl@0: 
sl@0: Depending upon the hardware architecture, whilst an image is mapped the GPU may be
sl@0: denied access to the pixel data, so this function may cause GPU operations that use
sl@0: this image to fail if proper synchronisation is not provided by means of the
sl@0: mechanisms available from the different rendering pipelines or from specialised
sl@0: synchronisation objects. Likewise, if the GPU is using the image at the time this
sl@0: function is called, the mapping may fail with KErrInUse. Note that even if operations
sl@0: do not fail, the results are not guaranteed to be correct unless proper synchronisation
sl@0: is provided.
sl@0: 
sl@0: @param aDataAddress On return, the base address of the pixel data in the address
sl@0:        space of the calling process.
sl@0: @param aDataStride On return, the number of bytes between rows of the pixel data.
sl@0: @pre The Graphics Resource driver is initialised for use in the context of the
sl@0:      calling process.
sl@0: @pre This RSgImage handle is valid and not null.
sl@0: @pre The image is not mapped yet.
sl@0: @pre The image was created with CPU access ESgCpuAccessReadWrite.
sl@0: @pre The image was created by the calling process.
sl@0: @post The pixel data of the image is directly accessible in the address space of the
sl@0:       calling process for reading and writing, until Unmap() is called.
sl@0: @return KErrNone if successful.
sl@0: @return KErrBadHandle if this RSgImage handle is null.
sl@0: @return KErrInUse if the image is already mapped or in exclusive use by the GPU.
sl@0: @return KErrAccessDenied if the image was not created with CPU access
sl@0:         ESgCpuAccessReadWrite.
sl@0: @return KErrPermissionDenied if the image was created by another process.
sl@0: @return KErrNoMemory if there is not enough system memory.
sl@0: @panic SGRES 3 in debug builds if this RSgImage handle is invalid.
sl@0: @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
sl@0:        for use in the context of the calling process.
sl@0: */
sl@0: EXPORT_C TInt RSgImage::MapReadWrite(TAny*& aDataAddress, TInt& aDataStride)
sl@0: 	{
sl@0: 	if (!iImpl)
sl@0: 		{
sl@0: 		return KErrBadHandle;
sl@0: 		}
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Wait();
sl@0: 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
sl@0: 	__ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
sl@0: #endif
sl@0: 	TInt err = static_cast<MSgImageAdapter*>(iImpl)->MapReadWrite(aDataAddress, aDataStride);
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Signal();
sl@0: #endif
sl@0: 	return err;
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype
sl@0: @deprecated
sl@0: 
sl@0: Makes the pixel data of an image no longer accessible by the CPU. If the image was
sl@0: mapped for writing by the CPU, any written data is retained and any subsequent usage
sl@0: of the image by the GPU will reflect its new state.
sl@0: 
sl@0: If the last handle to an image in a process is closed while the image is still mapped
sl@0: by the process then the image will be automatically unmapped.
sl@0: 
sl@0: @pre The Graphics Resource driver is initialised for use in the context of the
sl@0:      calling process.
sl@0: @pre This RSgImage handle is valid and not null.
sl@0: @pre The image is mapped for CPU access by a previous call to MapReadOnly(),
sl@0:      MapWriteOnly() or MapReadWrite().
sl@0: @post The GPU is guaranteed to be able to get access to the image.
sl@0: @post The address range in the calling process used for the mapping is no longer
sl@0:       valid. Attempts by the calling process to access any address in this range
sl@0:       will result in undefined behaviour.
sl@0: @return KErrNone if successful.
sl@0: @return KErrBadHandle if this RSgImage handle is null.
sl@0: @return KErrGeneral if the image was not mapped for CPU access.
sl@0: @panic SGRES 3 in debug builds if this RSgImage handle is invalid.
sl@0: @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
sl@0:        for use in the context of the calling process.
sl@0: */
sl@0: EXPORT_C TInt RSgImage::Unmap() const
sl@0: 	{
sl@0: 	if (!iImpl)
sl@0: 		{
sl@0: 		return KErrBadHandle;
sl@0: 		}
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Wait();
sl@0: 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
sl@0: 	__ASSERT_DEBUG(gPls.iDriver->CheckImage(*iImpl), Panic(ESgPanicBadImageHandle));
sl@0: #endif
sl@0: 	TInt err = static_cast<MSgImageAdapter*>(iImpl)->Unmap();
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Signal();
sl@0: #endif
sl@0: 	return err;
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype
sl@0: @deprecated
sl@0: 
sl@0: Retrieves the list of image pixel formats supported on this device for a specified
sl@0: usage. This function is often called before creating images.
sl@0: 
sl@0: @param aInfo The image attributes. aInfo.iPixelFormat is ignored.
sl@0: @param aPixelFormats A pointer to an array that on return will contain the supported
sl@0:        pixel formats. If this parameter is null, then this function will just
sl@0:        return the number of supported pixel formats in aCount.
sl@0: @param aCount On input, the number of elements in the array pointed to by aPixelFormats
sl@0:        if not null, ignored otherwise. On return, the actual number of supported pixel
sl@0:        formats. If this number is greater than the number of elements in the array,
sl@0:        then the array will be filled with as many pixel formats as it can hold and the
sl@0:        function will return KErrOverflow.
sl@0: @pre The Graphics Resource driver is initialised for use in the context of the
sl@0:      calling process.
sl@0: @pre aInfo is valid.
sl@0: @pre If aPixelFormats is not null then aCount is greater than zero.
sl@0: @post None.
sl@0: @return KErrNone if successful.
sl@0: @return KErrArgument if aInfo is invalid or if aPixelFormats is not null and aCount
sl@0:         is negative.
sl@0: @return KErrOverflow if the actual number of supported pixel formats is greater than
sl@0:         the number of elements in the array pointed to by aPixelFormats.
sl@0: @return KErrNoMemory if there is not enough system memory.
sl@0: @panic SGRES 5 in debug builds if the Graphics Resource driver is not initialised
sl@0:        for use in the context of the calling process.
sl@0: */
sl@0: EXPORT_C TInt RSgImage::GetPixelFormats(const TSgImageInfo& aInfo, TUidPixelFormat* aPixelFormats, TInt& aCount)
sl@0: 	{
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Wait();
sl@0: 	__ASSERT_DEBUG(gPls.iDriver, Panic(ESgPanicNoDriver));
sl@0: #endif
sl@0: 	TInt err = gPls.iDriver->GetPixelFormats(aInfo, aPixelFormats, aCount);
sl@0: #ifdef _DEBUG
sl@0: 	gPls.iMutex.Signal();
sl@0: #endif
sl@0: 	return err;
sl@0: 	}