CrystalSpace

Public API Reference

iView Struct Reference

The iView class represents a viewport and encapsulates the top-level renderer interface. More...

#include <ivaria/view.h>

Inheritance diagram for iView:

List of all members.

Public Member Functions

virtual void AddViewVertex (int x, int y)=0
 Add a vertex to the clipping polygon (non-rectangular clipping).
virtual void ClearView ()=0
 Clear the clipper in order to start building a new polygon-based clipper.
virtual void Draw (iMeshWrapper *mesh=0)=0
 Render the scene as seen from the camera.
virtual void DrawBackground (iGraphics3D *g3d)=0
 Draw the background of this view.
virtual const csColor4GetBackgroundColor () const =0
 Get the background color of this view.
virtual iTextureHandleGetBackgroundTexture (int &sx, int &sy, int &sw, int &sh, int &tx, int &ty, int &tw, int &th, uint8 &alpha, bool &tiled) const =0
 Get the background texture of this view.
virtual iCameraGetCamera ()=0
 Get the current camera.
virtual iClipper2DGetClipper ()=0
 Return the current clipper. This function may call UpdateClipper().
virtual iGraphics3DGetContext ()=0
 Get the iGraphics3d context of this view.
virtual iCustomMatrixCameraGetCustomMatrixCamera ()=0
 Get the current custom matrix camera.
virtual iEngineGetEngine ()=0
 Get the engine handle.
virtual int GetHeight () const =0
 Get the view height, in pixels.
virtual CS::Utility::MeshFilterGetMeshFilter ()=0
 Get the mesh filter used to restrict the meshes that are visible in this view.
virtual iPerspectiveCameraGetPerspectiveCamera ()=0
 Get the current perspective camera.
virtual int GetWidth () const =0
 Get the view width, in pixels.
virtual csVector3 InvProject (const csVector2 &p, float z) const =0
 Calculate an inverse projection corrected point for this view, that is the inverse projection of a 2D point expressed in screen space into the 3D camera space.
virtual csVector2 NormalizedToScreen (const csVector2 &pos)=0
 Transform a normalized screen space coordinate (-1 to 1) to real pixels in this viewport.
virtual csVector2 Project (const csVector3 &v) const =0
 Calculate a projection corrected point for this view, that is the projection of a 3D point expressed in camera space into the 2D screen space.
virtual void RestrictClipperToScreen ()=0
 Clip the polygon clipper to the screen boundaries.
virtual csVector2 ScreenToNormalized (const csVector2 &pos)=0
 Transform a screen space coordinate in pixels to a normalized screen coordinate (-1 to 1).
virtual void SetAutoResize (bool state)=0
 Enable or disable automatic resizing.
virtual void SetBackgroundColor (csColor4 *color)=0
 Set the background color of this view.
virtual void SetBackgroundTexture (iTextureHandle *texture, int sx, int sy, int sw, int sh, int tx, int ty, int tw, int th, uint8 alpha, bool tiled)=0
 Set the background texture of this view.
virtual void SetCamera (iCamera *c)=0
 Set the current camera.
virtual void SetContext (iGraphics3D *ig3d)=0
 Set the iGraphics3d context of this view.
virtual void SetCustomMatrixCamera (iCustomMatrixCamera *c)=0
 Set the current camera as a custom matrix camera.
virtual void SetEngine (iEngine *e)=0
 Set the engine handle.
virtual void SetHeight (int h)=0
 Set the view height, in pixels.
virtual void SetPerspectiveCamera (iPerspectiveCamera *c)=0
 Set the current camera as a perspective camera.
virtual void SetRectangle (int x, int y, int w, int h, bool restrictToScreen=true)=0
 Set the clipper as a clipping rectangle.
virtual void SetWidth (int w)=0
 Set the view width, in pixels.
virtual void UpdateClipper ()=0
 Update the Clipper. This is called automatically by GetClipper().

Detailed Description

The iView class represents a viewport and encapsulates the top-level renderer interface.

It is basically a camera and a clipper, and is used to define how the view from the camera must be rendered into the render target.

The clipper is used to speed up the rendering process by excluding the objects that are not visible. It is returned by GetClipper() and can be defined either through a rectangle (methods SetWidth(), SetHeight() and SetRectangle()) or through a custom polygon (methods ClearView(), AddViewVertex() and RestrictClipperToScreen()).

The clipper and view dimensions doesn't need to be updated if SetAutoResize() is set to true. If no clipper is provided and SetAutoResize() is set to true, then a rectangular one will be used with the size of the full screen.

The list of meshes to be rendered from the scene can also be restricted using the method GetMeshFilter().

A background can be defined for the view, it will be displayed before any other graphics when the view is rendered. The background can be a combination of a color (SetBackgroundColor()) and a texture that can be tiled (SetBackgroundTexture()). The background is clipped against the current clipper, or against the rectangular bounding box of the clipper if it is a custom polygon.

If you don't want the current 2D canvas to be overwritten when rendering this view, eg if you want to superpose the rendering of several views, then you can set a null background by calling SetBackgroundColor() with a null pointer.

Remarks:
The view coordinates are vertically mirrored in comparison to screen space, i.e. y=0 is at the bottom of the viewport, y=GetHeight() at the top.

Main creators of instances implementing this interface:

Main ways to get pointers to this interface:

Main users of this interface:

Definition at line 83 of file view.h.


Member Function Documentation

virtual void iView::AddViewVertex ( int  x,
int  y 
) [pure virtual]

Add a vertex to the clipping polygon (non-rectangular clipping).

If the current clipper was a rectangle, then it will be deleted.

Parameters:
x The X coordinate of the vertex, in pixels.
y The Y coordinate of the vertex, in pixels.

Implemented in csView.

virtual void iView::ClearView (  )  [pure virtual]

Clear the clipper in order to start building a new polygon-based clipper.

Implemented in csView.

virtual void iView::Draw ( iMeshWrapper mesh = 0  )  [pure virtual]

Render the scene as seen from the camera.

Parameters:
mesh This parameter was previously used to restrict the rendering of the view to a single mesh, but it is not used anymore. You should use GetMeshFilter() instead.

Implemented in csView.

virtual void iView::DrawBackground ( iGraphics3D g3d  )  [pure virtual]

Draw the background of this view.

This is usually the responsability of the iRenderManager to call this method, hence you shouldn't need to call it manually.

Parameters:
g3d The 3D canvas where to render the background.

Implemented in csView.

virtual const csColor4* iView::GetBackgroundColor (  )  const [pure virtual]

Get the background color of this view.

This will be displayed before any other graphics when this view is rendered.

Implemented in csView.

virtual iTextureHandle* iView::GetBackgroundTexture ( int &  sx,
int &  sy,
int &  sw,
int &  sh,
int &  tx,
int &  ty,
int &  tw,
int &  th,
uint8 &  alpha,
bool &  tiled 
) const [pure virtual]

Get the background texture of this view.

This will be displayed before any other graphics when this view is rendered (but just after the background color).

Parameters:
sx The X coordinate of the left of the texture on screen.
sy The Y coordinate of the top of the texture on screen.
sw The width of the texture on screen.
sh The height of the texture on screen.
tx The X coordinate of the left of the displayed texture area.
ty The Y coordinate of the top of the displayed texture area.
tw The width of the displayed texture area.
th The height of the displayed texture area.
alpha The transparency of the texture.
tiled Whether the texture should be displayed once or repeated in order to cover the whole screen.
Returns:
The background texture.

Implemented in csView.

virtual iCamera* iView::GetCamera (  )  [pure virtual]

Get the current camera.

Implemented in csView.

virtual iClipper2D* iView::GetClipper (  )  [pure virtual]

Return the current clipper. This function may call UpdateClipper().

Implemented in csView.

virtual iGraphics3D* iView::GetContext (  )  [pure virtual]

Get the iGraphics3d context of this view.

Implemented in csView.

virtual iCustomMatrixCamera* iView::GetCustomMatrixCamera (  )  [pure virtual]

Get the current custom matrix camera.

Can return nullptr if the current camera is not a custom matrix camera.

Implemented in csView.

virtual iEngine* iView::GetEngine (  )  [pure virtual]

Get the engine handle.

Implemented in csView.

virtual int iView::GetHeight (  )  const [pure virtual]

Get the view height, in pixels.

Implemented in csView.

virtual CS::Utility::MeshFilter& iView::GetMeshFilter (  )  [pure virtual]

Get the mesh filter used to restrict the meshes that are visible in this view.

Implemented in csView.

virtual iPerspectiveCamera* iView::GetPerspectiveCamera (  )  [pure virtual]

Get the current perspective camera.

Can return nullptr if the current camera is not a perspective camera.

Implemented in csView.

virtual int iView::GetWidth (  )  const [pure virtual]

Get the view width, in pixels.

Implemented in csView.

virtual csVector3 iView::InvProject ( const csVector2 p,
float  z 
) const [pure virtual]

Calculate an inverse projection corrected point for this view, that is the inverse projection of a 2D point expressed in screen space into the 3D camera space.

Parameters:
p The 2D point on the screen, in pixels.
z The Z component of the projection point, that is the distance between the camera and the plane where the point is projected.
Returns:
The 3D projection point, in camera space coordinates.
See also:
Project() iCamera::InvProject()

Implemented in csView.

virtual csVector2 iView::NormalizedToScreen ( const csVector2 pos  )  [pure virtual]

Transform a normalized screen space coordinate (-1 to 1) to real pixels in this viewport.

Remarks:
Unlike csEngineTools::NormalizedToScreen(), this method works in view space, not in screen space. That is, the view coordinates are vertically mirrored in comparison to screen space, i.e. y=0 is at the bottom of the viewport, and y=GetHeight() at the top.

Implemented in csView.

virtual csVector2 iView::Project ( const csVector3 v  )  const [pure virtual]

Calculate a projection corrected point for this view, that is the projection of a 3D point expressed in camera space into the 2D screen space.

Parameters:
v The 3D point to be projected, in camera space coordinates.
Returns:
The 2D projection into the screen, in pixels.
See also:
InvProject() iCamera::Project()

Implemented in csView.

virtual void iView::RestrictClipperToScreen (  )  [pure virtual]

Clip the polygon clipper to the screen boundaries.

Implemented in csView.

virtual csVector2 iView::ScreenToNormalized ( const csVector2 pos  )  [pure virtual]

Transform a screen space coordinate in pixels to a normalized screen coordinate (-1 to 1).

Remarks:
Unlike csEngineTools::NormalizedToScreen(), this method works in view space, not in screen space. That is, the view coordinates are vertically mirrored in comparison to screen space, i.e. y=0 is at the bottom of the viewport, and y=GetHeight() at the top.

Implemented in csView.

virtual void iView::SetAutoResize ( bool  state  )  [pure virtual]

Enable or disable automatic resizing.

When this is true (default) then the view will detect automatically when the canvas size changes and adapt the view and camera automatically (i.e. it will change the view rectangle, the clipper coordinates and the camera aspect ratio). If you don't want that then you can disable this.

Implemented in csView.

virtual void iView::SetBackgroundColor ( csColor4 color  )  [pure virtual]

Set the background color of this view.

This will be displayed before any other graphics when this view is rendered.

If it is set to nullptr, then no background color will be displayed and the 2D canvas won't be cleared before the view is rendered. This can be used e.g. in order to superpose the rendering of several views.

The default is a black, non transparent, background color.

Implemented in csView.

virtual void iView::SetBackgroundTexture ( iTextureHandle texture,
int  sx,
int  sy,
int  sw,
int  sh,
int  tx,
int  ty,
int  tw,
int  th,
uint8  alpha,
bool  tiled 
) [pure virtual]

Set the background texture of this view.

This will be displayed before any other graphics when this view is rendered (but just after the background color).

Remarks:
Unlike the other methods of iView that uses flipped vertical coordinates, this method uses the same logic as iGraphics2D::DrawPixmap(), that is, y=0 is at the top of the screen while y=GetHeight() is at the bottom.
Parameters:
texture The background texture.
sx The X coordinate of the left of the texture on screen.
sy The Y coordinate of the top of the texture on screen.
sw The width of the texture on screen.
sh The height of the texture on screen.
tx The X coordinate of the left of the displayed texture area.
ty The Y coordinate of the top of the displayed texture area.
tw The width of the displayed texture area.
th The height of the displayed texture area.
alpha The transparency of the texture.
tiled Whether the texture should be displayed once or repeated in order to cover the whole screen.

Implemented in csView.

virtual void iView::SetCamera ( iCamera c  )  [pure virtual]

Set the current camera.

Implemented in csView.

virtual void iView::SetContext ( iGraphics3D ig3d  )  [pure virtual]

Set the iGraphics3d context of this view.

Implemented in csView.

virtual void iView::SetCustomMatrixCamera ( iCustomMatrixCamera c  )  [pure virtual]

Set the current camera as a custom matrix camera.

Implemented in csView.

virtual void iView::SetEngine ( iEngine e  )  [pure virtual]

Set the engine handle.

Implemented in csView.

virtual void iView::SetHeight ( int  h  )  [pure virtual]

Set the view height, in pixels.

Implemented in csView.

virtual void iView::SetPerspectiveCamera ( iPerspectiveCamera c  )  [pure virtual]

Set the current camera as a perspective camera.

Implemented in csView.

virtual void iView::SetRectangle ( int  x,
int  y,
int  w,
int  h,
bool  restrictToScreen = true 
) [pure virtual]

Set the clipper as a clipping rectangle.

Parameters:
x The left position of the rectangle, in pixels.
y The bottom position of the rectangle, in pixels.
w The width of the rectangle, in pixels.
h The height of the rectangle, in pixels.
restrictToScreen Restrict the rectangle to not be bigger than the screen size.

Implemented in csView.

virtual void iView::SetWidth ( int  w  )  [pure virtual]

Set the view width, in pixels.

Implemented in csView.

virtual void iView::UpdateClipper (  )  [pure virtual]

Update the Clipper. This is called automatically by GetClipper().

Implemented in csView.


The documentation for this struct was generated from the following file:

Generated for Crystal Space 2.1 by doxygen 1.6.1