sf::RenderTexture Class Reference
[Graphics module]

Target for off-screen 2D rendering into an texture. More...

#include <RenderTexture.hpp>

Inheritance diagram for sf::RenderTexture:
sf::RenderTarget sf::NonCopyable

List of all members.

Public Member Functions

 RenderTexture ()
 Default constructor.
virtual ~RenderTexture ()
 Destructor.
bool Create (unsigned int width, unsigned int height, bool depthBuffer=false)
 Create the render-texture.
void SetSmooth (bool smooth)
 Enable or disable texture smoothing.
bool IsSmooth () const
 Tell whether the smooth filtering is enabled or not.
bool SetActive (bool active=true)
 Activate of deactivate the render-texture for rendering.
void Display ()
 Update the contents of the target texture.
virtual unsigned int GetWidth () const
 Return the width of the rendering region of the texture.
virtual unsigned int GetHeight () const
 Return the height of the rendering region of the texture.
const TextureGetTexture () const
 Get a read-only reference to the target texture.
void Clear (const Color &color=Color(0, 0, 0, 255))
 Clear the entire target with a single color.
void Draw (const Drawable &object)
 Draw an object into the target.
void Draw (const Drawable &object, const Shader &shader)
 Draw an object into the target with a shader.
void SetView (const View &view)
 Change the current active view.
const ViewGetView () const
 Retrieve the view currently in use in the render target.
const ViewGetDefaultView () const
 Get the default view of the render target.
IntRect GetViewport (const View &view) const
 Get the viewport of a view, applied to this render target.
Vector2f ConvertCoords (unsigned int x, unsigned int y) const
 Convert a point from target coordinates to view coordinates.
Vector2f ConvertCoords (unsigned int x, unsigned int y, const View &view) const
 Convert a point from target coordinates to view coordinates.
void SaveGLStates ()
 Save the current OpenGL render states and matrices.
void RestoreGLStates ()
 Restore the previously saved OpenGL render states and matrices.

Protected Member Functions

void Initialize ()
 Performs the common initialization step after creation.

Detailed Description

Target for off-screen 2D rendering into an texture.

sf::RenderTexture is the little brother of sf::RenderWindow.

It implements the same 2D drawing and OpenGL-related functions (see their base class sf::RenderTarget for more details), the difference is that the result is stored in an off-screen texture rather than being show in a window.

Rendering to a texture can be useful in a variety of situations:

Usage example:

 // Create a new render-window
 sf::RenderWindow window(sf::VideoMode(800, 600), "SFML window");

 // Create a new render-texture
 sf::RenderTexture texture;
 if (!texture.Create(500, 500))
     return -1

 // The main loop
 while (window.IsOpened())
 {
    // Event processing
    // ...

    // Clear the whole texture with red color
    texture.Clear(sf::Color::Red);

    // Draw stuff to the texture
    texture.Draw(sprite);  // sprite is a sf::Sprite
    texture.Draw(shape);   // shape is a sf::Shape
    texture.Draw(text);    // text is a sf::Text

    // We're done drawing to the texture
    texture.Display();

    // Now we start rendering to the window, clear it first
    window.Clear();

    // Draw the texture
    sf::Sprite sprite(texture.GetTexture());
    window.Draw(sprite);

    // End the current frame and display its contents on screen
    window.Display();
 }

Like sf::RenderWindow, sf::RenderTexture is still able to render direct OpenGL stuff. It is even possible to mix together OpenGL calls and regular SFML drawing commands. If you need a depth buffer for 3D rendering, don't forget to request it when calling RenderTexture::Create.

See also:
sf::RenderTarget, sf::RenderWindow, sf::View, sf::Texture

Definition at line 46 of file RenderTexture.hpp.


Constructor & Destructor Documentation

sf::RenderTexture::RenderTexture (  ) 

Default constructor.

Constructs an empty, invalid render-texture. You must call Create to have a valid render-texture.

See also:
Create
virtual sf::RenderTexture::~RenderTexture (  )  [virtual]

Destructor.


Member Function Documentation

void sf::RenderTarget::Clear ( const Color color = Color(0, 0, 0, 255)  )  [inherited]

Clear the entire target with a single color.

This function is usually called once every frame, to clear the previous contents of the target.

Parameters:
color Fill color to use to clear the render target
Vector2f sf::RenderTarget::ConvertCoords ( unsigned int  x,
unsigned int  y,
const View view 
) const [inherited]

Convert a point from target coordinates to view coordinates.

Initially, a unit of the 2D world matches a pixel of the render target. But if you define a custom view, this assertion is not true anymore, ie. a point located at (10, 50) in your render target (for example a window) may map to the point (150, 75) in your 2D world -- for example if the view is translated by (140, 25).

For render windows, this function is typically used to find which point (or object) is located below the mouse cursor.

This version uses a custom view for calculations, see the other overload of the function to use the current view of the render target.

Parameters:
x X coordinate of the point to convert, relative to the render target
y Y coordinate of the point to convert, relative to the render target
view The view to use for converting the point
Returns:
The converted point, in "world" units
Vector2f sf::RenderTarget::ConvertCoords ( unsigned int  x,
unsigned int  y 
) const [inherited]

Convert a point from target coordinates to view coordinates.

Initially, a unit of the 2D world matches a pixel of the render target. But if you define a custom view, this assertion is not true anymore, ie. a point located at (10, 50) in your render target (for example a window) may map to the point (150, 75) in your 2D world -- for example if the view is translated by (140, 25).

For render windows, this function is typically used to find which point (or object) is located below the mouse cursor.

This version uses the current view of the render target. See the other overload to specify a custom view.

Parameters:
x X coordinate of the point to convert, relative to the render target
y Y coordinate of the point to convert, relative to the render target
Returns:
The converted point, in "world" units
bool sf::RenderTexture::Create ( unsigned int  width,
unsigned int  height,
bool  depthBuffer = false 
)

Create the render-texture.

Before calling this function, the render-texture is in an invalid state, thus it is mandatory to call it before doing anything with the render-texture. The last parameter, depthBuffer, is useful if you want to use the render-texture for 3D OpenGL rendering that requires a depth-buffer. Otherwise it is unnecessary, and you should leave this parameter to false (which is its default value).

Parameters:
width Width of the render-texture
height Height of the render-texture
depthBuffer Do you want this render-texture to have a depth buffer?
Returns:
True if creation has been successful
void sf::RenderTexture::Display (  ) 

Update the contents of the target texture.

This function updates the target texture with what has been drawn so far. Like for windows, calling this function is mandatory at the end of rendering. Not calling it may leave the texture in an undefined state.

void sf::RenderTarget::Draw ( const Drawable object,
const Shader shader 
) [inherited]

Draw an object into the target with a shader.

This function draws anything that inherits from the sf::Drawable base class (sf::Sprite, sf::Shape, sf::Text, or even your own derived classes). The shader alters the way that the pixels are processed right before being written to the render target.

Parameters:
object Object to draw
shader Shader to use for drawing the object
void sf::RenderTarget::Draw ( const Drawable object  )  [inherited]

Draw an object into the target.

This function draws anything that inherits from the sf::Drawable base class (sf::Sprite, sf::Shape, sf::Text, or even your own derived classes).

Parameters:
object Object to draw
const View& sf::RenderTarget::GetDefaultView (  )  const [inherited]

Get the default view of the render target.

The default view has the initial size of the render target, and never changes after the target has been created.

Returns:
The default view of the render target
See also:
SetView, GetView
virtual unsigned int sf::RenderTexture::GetHeight (  )  const [virtual]

Return the height of the rendering region of the texture.

The returned value is the size that you passed to the Create function.

Returns:
Height in pixels
GetWidth

Implements sf::RenderTarget.

const Texture& sf::RenderTexture::GetTexture (  )  const

Get a read-only reference to the target texture.

After drawing to the render-texture and calling Display, you can retrieve the updated texture using this function, and draw it using a sprite (for example). The internal sf::Texture of a render-texture is always the same instance, so that it is possible to call this function once and keep a reference to the texture even after it is modified.

Returns:
Const reference to the texture
const View& sf::RenderTarget::GetView (  )  const [inherited]

Retrieve the view currently in use in the render target.

Returns:
The view object that is currently used
See also:
SetView, GetDefaultView
IntRect sf::RenderTarget::GetViewport ( const View view  )  const [inherited]

Get the viewport of a view, applied to this render target.

The viewport is defined in the view as a ratio, this function simply applies this ratio to the current dimensions of the render target to calculate the pixels rectangle that the viewport actually covers in the target.

Parameters:
view The view for which we want to compute the viewport
Returns:
Viewport rectangle, expressed in pixels
virtual unsigned int sf::RenderTexture::GetWidth (  )  const [virtual]

Return the width of the rendering region of the texture.

The returned value is the size that you passed to the Create function.

Returns:
Width in pixels
GetHeight

Implements sf::RenderTarget.

void sf::RenderTarget::Initialize (  )  [protected, inherited]

Performs the common initialization step after creation.

The derived classes must call this function after the target is created and ready for drawing.

bool sf::RenderTexture::IsSmooth (  )  const

Tell whether the smooth filtering is enabled or not.

Returns:
True if texture smoothing is enabled
See also:
SetSmooth
void sf::RenderTarget::RestoreGLStates (  )  [inherited]

Restore the previously saved OpenGL render states and matrices.

See the description of SaveGLStates to get a detailed description of these functions.

See also:
SaveGLStates
void sf::RenderTarget::SaveGLStates (  )  [inherited]

Save the current OpenGL render states and matrices.

This function can be used when you mix SFML drawing and direct OpenGL rendering. Combined with RestoreGLStates, it ensures that:

  • SFML's internal states are not messed up by your OpenGL code
  • your OpenGL states are not modified by a call to a SFML function

More specifically, it must be used around code that calls Draw functions. Example:

 // OpenGL code here...
 window.SaveGLStates();
 window.Draw(...);
 window.Draw(...);
 window.RestoreGLStates();
 // OpenGL code here...

Note that this function is quite expensive and should be used wisely. It is provided for convenience, and the best results will be achieved if you handle OpenGL states yourself (because you really know which states have really changed, and need to be saved / restored).

See also:
RestoreGLStates
bool sf::RenderTexture::SetActive ( bool  active = true  ) 

Activate of deactivate the render-texture for rendering.

This function makes the render-texture's context current for future OpenGL rendering operations (so you shouldn't care about it if you're not doing direct OpenGL stuff). Only one context can be current in a thread, so if you want to draw OpenGL geometry to another render target (like a RenderWindow) don't forget to activate it again.

Parameters:
active True to activate, false to deactivate
Returns:
True if operation was successful, false otherwise
void sf::RenderTexture::SetSmooth ( bool  smooth  ) 

Enable or disable texture smoothing.

This function is similar to Texture::SetSmooth. This parameter is enabled by default.

Parameters:
smooth True to enable smoothing, false to disable it
See also:
IsSmooth
void sf::RenderTarget::SetView ( const View view  )  [inherited]

Change the current active view.

The new view will affect everything that is drawn, until another view is activated. The render target keeps its own copy of the view object, so it is not necessary to keep the original one alive as long as it is in use. To restore the original view of the target, you can pass the result of GetDefaultView() to this function.

Parameters:
view New view to use
See also:
GetView, GetDefaultView

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