Target for off-screen 2D rendering into an texture. More...
#include <RenderTexture.hpp>
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 Texture & | GetTexture () 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 View & | GetView () const |
Retrieve the view currently in use in the render target. | |
const View & | GetDefaultView () 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. |
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.
Definition at line 46 of file RenderTexture.hpp.
sf::RenderTexture::RenderTexture | ( | ) |
Default constructor.
Constructs an empty, invalid render-texture. You must call Create to have a valid render-texture.
virtual sf::RenderTexture::~RenderTexture | ( | ) | [virtual] |
Destructor.
Clear the entire target with a single color.
This function is usually called once every frame, to clear the previous contents of the target.
color | Fill color to use to clear the render target |
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.
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 |
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.
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 |
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).
width | Width of the render-texture |
height | Height of the render-texture |
depthBuffer | Do you want this render-texture to have a depth buffer? |
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 | ) | [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).
object | Object to draw |
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.
object | Object to draw |
shader | Shader to use for drawing the object |
const View& sf::RenderTarget::GetDefaultView | ( | ) | const [inherited] |
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.
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.
const View& sf::RenderTarget::GetView | ( | ) | const [inherited] |
Retrieve the view currently in use in the render target.
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.
view | The view for which we want to compute the viewport |
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.
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.
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.
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:
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).
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.
active | True to activate, false to deactivate |
void sf::RenderTexture::SetSmooth | ( | bool | smooth | ) |
Enable or disable texture smoothing.
This function is similar to Texture::SetSmooth. This parameter is enabled by default.
smooth | True to enable smoothing, false to disable it |
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.
view | New view to use |