TRendererSurface Class Reference

This class represents a surface data from graphic device. More...

#include <RendererTypes.h>

List of all members.

Public Member Functions

virtual void Duplicate (TRendererSurface **dest)=0
 Duplicate pointer to this object to another one and increase number of references to it.
virtual BOOL IsRenderTarget (void) const =0
 Determines whether this surface may be used as render target to renderer device.
virtual BOOL IsDepthStencil (void) const =0
 Determines whether this surface may be used as depth-stencil surface in renderer device.
virtual BOOL IsLockable (void) const =0
 Determines whether this surface may be locked and readed/overwrited.
virtual BOOL IsDynamic (void) const =0
 Determines whether surface is dynamic (thus if it is created in dynamic texture).
virtual BOOL IsFromTexture (void) const =0
 Determines whether this surface was created as surface of texture.
virtual BOOL IsVolatile (void) const =0
 Determines whether this surface must recreated after renderer is lost.
virtual BOOL IsCompressed (void) const =0
 Determines whether surface has compressed format.
virtual EnumGraphicPool GetPool (void) const =0
 Returns pool where this surface is stored.
virtual TSurfaceDesc GetSurfDesc (void) const =0
 Return surface description.
virtual DWORD GetWidth (void) const =0
 Returns width of main surface.
virtual DWORD GetHeight (void) const =0
 Returns height of main surface.
virtual EnumGraphicFormat GetPixelFormat (void) const =0
 Returns pixel format of surface.
virtual DWORD GetBlockSize (void) const =0
 Returns size of block in surface.
virtual BOOL UpdateSurface (const TGraphicSurface *source)=0
 Update entire surface.
virtual BOOL UpdateSurfaceDynamic (const TGraphicSurface *source)=0
 Update entire dynamic surface.
virtual BOOL UpdateSurfaceRect (const TGraphicSurface *source, const TRect *dest_rect, const TRect *src_rect)=0
 Update specified rectangle of surface.
virtual BOOL ReadSurface (TGraphicSurface *destination)=0
 Copy data from this surface into software surface (TGraphicSurface).
virtual BOOL ReadSurfaceRect (TGraphicSurface *destination, const TRect *dest_rect, const TRect *src_rect)=0
 Copy data from specified rectangle on this surface into specified rectangle in software surface (TGraphicSurface).
virtual BOOL UpdateRenderTargetSurface (TRendererSurface *source)=0
 Update this surface which must be created as render-target in VIDEO memory from surface created in RAM memory.
virtual BOOL ReadRenderTargetSurface (TRendererSurface *destination)=0
 Read data from this surface created as render-target in VIDEO memory and save it into surface created in RAM memory.
virtual DWORD GetRefs (void) const =0
 Returns number of references to this object.
virtual DWORD AddRefs (void)=0
 Increases number of references and returns result.
virtual DWORD Release (void)=0
 Decreases number of references to this surface and return result.


Detailed Description

This class represents a surface data from graphic device.

You can create object of this type only via TRenderer object. Only dynamic instances of this class can be created because releasing this class is implemented via Release() method that performs self-destroying of object via operator delete if number of references count to zero.

Because this class has reference-counting and only pointers to this object should be used, method AddRefs() and Release() should be used carefully. For example if you create copy of pointer to TRendererSurface (simple assignment) you must after this operation call AddRefs() that increases number of references to object and it ensures properly destroying of object when reference-count reachs to zero. Safe way how assign pointer is via Duplicate() methods.

This class has no SetXXX methods, friend class and functions set object's members directly while creating instances.

Definition at line 699 of file RendererTypes.h.


Member Function Documentation

virtual DWORD TRendererSurface::AddRefs void   )  [pure virtual]
 

Increases number of references and returns result.

virtual void TRendererSurface::Duplicate TRendererSurface **  dest  )  [pure virtual]
 

Duplicate pointer to this object to another one and increase number of references to it.

This method does the same as copying two pointers and increasing number of references with calling AddRefs().

Parameters:
dest [out] adress of pointer to store result

virtual DWORD TRendererSurface::GetBlockSize void   )  const [pure virtual]
 

Returns size of block in surface.

For non-compressed formats returns always 1. See IsCompressed(). Block is number in pixels in vertical (or horizontal) direction and it is basic unit of compressed textures.

virtual DWORD TRendererSurface::GetHeight void   )  const [pure virtual]
 

Returns height of main surface.

virtual EnumGraphicFormat TRendererSurface::GetPixelFormat void   )  const [pure virtual]
 

Returns pixel format of surface.

virtual EnumGraphicPool TRendererSurface::GetPool void   )  const [pure virtual]
 

Returns pool where this surface is stored.

virtual DWORD TRendererSurface::GetRefs void   )  const [pure virtual]
 

Returns number of references to this object.

virtual TSurfaceDesc TRendererSurface::GetSurfDesc void   )  const [pure virtual]
 

Return surface description.

virtual DWORD TRendererSurface::GetWidth void   )  const [pure virtual]
 

Returns width of main surface.

virtual BOOL TRendererSurface::IsCompressed void   )  const [pure virtual]
 

Determines whether surface has compressed format.

This is useful for surface locking because compressed formats must be locked on block boundaries. See GetBlockSize().

virtual BOOL TRendererSurface::IsDepthStencil void   )  const [pure virtual]
 

Determines whether this surface may be used as depth-stencil surface in renderer device.

virtual BOOL TRendererSurface::IsDynamic void   )  const [pure virtual]
 

Determines whether surface is dynamic (thus if it is created in dynamic texture).

virtual BOOL TRendererSurface::IsFromTexture void   )  const [pure virtual]
 

Determines whether this surface was created as surface of texture.

virtual BOOL TRendererSurface::IsLockable void   )  const [pure virtual]
 

Determines whether this surface may be locked and readed/overwrited.

Only surfaces created as MANAGED or in system RAM may be modified directly, surfaces in VIDEO memory must be modified with special method from renderer or cannot be modified. For type of surface pool see EnumGraphicPool and GetPool() method.

virtual BOOL TRendererSurface::IsRenderTarget void   )  const [pure virtual]
 

Determines whether this surface may be used as render target to renderer device.

virtual BOOL TRendererSurface::IsVolatile void   )  const [pure virtual]
 

Determines whether this surface must recreated after renderer is lost.

Remark: Only resources in VIDEO memory must be recreated thus you must hold their backup copy in your program!!!

virtual BOOL TRendererSurface::ReadRenderTargetSurface TRendererSurface destination  )  [pure virtual]
 

Read data from this surface created as render-target in VIDEO memory and save it into surface created in RAM memory.

This method directly call TRenderer::ReadRenderTargetSurface method. This is the only one way how to read data from render-target surface in VIDEO memory. Both surfaces must have identical pixel format and dimensions! This method always returns valid values.

Parameters:
destination [in] destination surface created in RAM memory, see TRendererSurface::GetPool()

virtual BOOL TRendererSurface::ReadSurface TGraphicSurface destination  )  [pure virtual]
 

Copy data from this surface into software surface (TGraphicSurface).

This method directly call TRenderer::ReadSurface method. Both surfaces must have the same pixelformat and size. This (source) surface must be lockable and must be created as MANAGED or RAM - see TRendererSurface::IsLockable() method. It means that must be created as MANAGED or in RAM. Surfaces stored in VIDEO memory cannot be readed with this method. This method always returns valid values.

Parameters:
destination [in,out] software surface as destination surface (must be valid, see TGraphicSurface::IsLoaded() method)

virtual BOOL TRendererSurface::ReadSurfaceRect TGraphicSurface destination,
const TRect dest_rect,
const TRect src_rect
[pure virtual]
 

Copy data from specified rectangle on this surface into specified rectangle in software surface (TGraphicSurface).

This method directly call TRenderer::ReadSurfaceRect method. Both surfaces must have the same pixelformat, size may be different, but size of both rectangles must be identical and both rectangles must be inside their surfaces. This (source) surface must be lockable - see TRendererSurface::IsLockable() method. It means that must be created as MANAGED or in RAM. Surfaces stored in VIDEO memory cannot be read with this method. This method always returns valid values.

Parameters:
destination [in,out] software surface for store result (must be valid, see TGraphicSurface::IsLoaded() method)
dest_rect [in] rectangle on destination surface
src_rect [in] rectangle on source surface

virtual DWORD TRendererSurface::Release void   )  [pure virtual]
 

Decreases number of references to this surface and return result.

If number of references count zero then surface is destroyed via operator delete. After calling this method pointer is invalid and must be set to NULL.

virtual BOOL TRendererSurface::UpdateRenderTargetSurface TRendererSurface source  )  [pure virtual]
 

Update this surface which must be created as render-target in VIDEO memory from surface created in RAM memory.

This method directly call TRenderer::UpdateRenderTargetSurface method. This is the only one way how to upload data into render-target surface in VIDEO memory. Both surfaces must have identical pixel format and dimensions! This method always returns valid values.

Parameters:
source [in] source surface created in RAM memory, see TRendererSurface::GetPool()

virtual BOOL TRendererSurface::UpdateSurface const TGraphicSurface source  )  [pure virtual]
 

Update entire surface.

This method directly call TRenderer::UpdateSurface method. This method can be called only on surface created as MANAGED or in RAM memory . Surfaces stored in VIDEO memory cannot be updated with this method.

Parameters:
source [in] source surface which must have same dimensions and pixelformat and must be lockable (created in MANAGED or RAM pool)

virtual BOOL TRendererSurface::UpdateSurfaceDynamic const TGraphicSurface source  )  [pure virtual]
 

Update entire dynamic surface.

This method directly call TRenderer::UpdateSurfaceDynamic method. This method can be called only on surface created as DYNAMIC (thus created in dynamic texture)

Parameters:
source [in] source surface which must have same dimensions and pixelformat and must be lockable (created in VIDEO pool as DYNAMIC)

virtual BOOL TRendererSurface::UpdateSurfaceRect const TGraphicSurface source,
const TRect dest_rect,
const TRect src_rect
[pure virtual]
 

Update specified rectangle of surface.

This method directly call TRenderer::UpdateSurfaceRect method. This method can be called only on surface created as MANAGED or in RAM memory. Both surfaces must have the same pixelformat, size may be different, but size of both rectangles must be identical. of both rectangles must be identical and both rectabgles must be inside their surfaces. Destination surface must be lockable - see TRendererSurface::IsLockable() method. It means that must be created as MANAGED or in RAM. Surfaces stored in VIDEO memory cannot be updated with this method. This method always returns valid values.

Parameters:
source [in] software surface as source surface (must be valid, see TGraphicSurface::IsLoaded() method)
dest_rect [in] rectangle on destination (this) surface
src_rect [in] rectangle on source surface


The documentation for this class was generated from the following file:
Generated on Wed Nov 28 22:43:44 2007 for Joy4D by  doxygen 1.4.6-NO