Target for off-screen 2D rendering into an image. More...
#include <RenderImage.hpp>
Public Member Functions | |
| RenderImage () | |
| Default constructor. | |
| virtual | ~RenderImage () |
| Destructor. | |
| bool | Create (unsigned int width, unsigned int height, bool depthBuffer=false) |
| Create the render-image. | |
| void | SetSmooth (bool smooth) |
| Enable or disable image smoothing. | |
| bool | IsSmooth () const |
| Tell whether the smooth filtering is enabled or not. | |
| bool | SetActive (bool active=true) |
| Activate of deactivate the render-image for rendering. | |
| void | Display () |
| Update the contents of the target image. | |
| virtual unsigned int | GetWidth () const |
| Return the width of the rendering region of the image. | |
| virtual unsigned int | GetHeight () const |
| Return the height of the rendering region of the image. | |
| const Image & | GetImage () const |
| Get a read-only reference to the target image. | |
| void | Clear (const Color &color=Color(0, 0, 0)) |
| 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. | |
Static Public Member Functions | |
| static bool | IsAvailable () |
| Check whether the system supports render images or not. | |
Protected Member Functions | |
| void | Initialize () |
| Performs the common initialization step after creation. | |
Target for off-screen 2D rendering into an image.
sf::RenderImage 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 image rather than being show in a window.
Rendering to an image can be useful in a variety of situations:
Usage example:
// First of all: make sure that rendering to image is supported if (!sf::RenderImage::IsAvailable()) return -1; // Create a new render-window sf::RenderWindow window(sf::VideoMode(800, 600), "SFML window"); // Create a new render-image sf::RenderImage image; if (!image.Create(500, 500)) return -1 // The main loop while (window.IsOpened()) { // Event processing // ... // Clear the whole image with red color image.Clear(sf::Color::Red); // Draw stuff to the image image.Draw(sprite); // sprite is a sf::Sprite image.Draw(shape); // shape is a sf::Shape image.Draw(text); // text is a sf::Text // We're done drawing to the image image.Display(); // Now we start rendering to the window, clear it first window.Clear(); // Draw the image sf::Sprite sprite(image.GetImage()); window.Draw(sprite); // End the current frame and display its contents on screen window.Display(); }
Like sf::RenderWindow, sf::RenderImage 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 RenderImage::Create.
Definition at line 46 of file RenderImage.hpp.
| sf::RenderImage::RenderImage | ( | ) |
Default constructor.
Constructs an empty, invalid render-image. You must call Create to have a valid render-image.
Definition at line 37 of file RenderImage.cpp.
| sf::RenderImage::~RenderImage | ( | ) | [virtual] |
Destructor.
Definition at line 45 of file RenderImage.cpp.
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 |
Definition at line 57 of file RenderTarget.cpp.
| 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 |
Definition at line 169 of file RenderTarget.cpp.
| 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 |
Definition at line 162 of file RenderTarget.cpp.
| bool sf::RenderImage::Create | ( | unsigned int | width, | |
| unsigned int | height, | |||
| bool | depthBuffer = false | |||
| ) |
Create the render-image.
Before calling this function, the render-image is in an invalid state, thus it is mandatory to call it before doing anything with the render-image. The last parameter, depthBuffer, is useful if you want to use the render-image 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-image | |
| height | Height of the render-image | |
| depthBuffer | Do you want this render-image to have a depth buffer? |
Definition at line 52 of file RenderImage.cpp.
| void sf::RenderImage::Display | ( | ) |
Update the contents of the target image.
This function updates the target image 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 image in an undefined state.
Definition at line 117 of file RenderImage.cpp.
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 |
Definition at line 95 of file RenderTarget.cpp.
| 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 |
Definition at line 65 of file RenderTarget.cpp.
| 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.
Definition at line 141 of file RenderTarget.cpp.
| unsigned int sf::RenderImage::GetHeight | ( | ) | const [virtual] |
Return the height of the rendering region of the image.
The returned value is the size that you passed to the Create function.
Implements sf::RenderTarget.
Definition at line 139 of file RenderImage.cpp.
| const Image & sf::RenderImage::GetImage | ( | ) | const |
Get a read-only reference to the target image.
After drawing to the render-image and calling Display, you can retrieve the updated image using this function, and draw it using a sprite (for example). The internal sf::Image of a render-image is always the same instance, so that it is possible to call this function once and keep a reference to the image even after is it modified.
Definition at line 146 of file RenderImage.cpp.
| const View & sf::RenderTarget::GetView | ( | ) | const [inherited] |
Retrieve the view currently in use in the render target.
Definition at line 134 of file RenderTarget.cpp.
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 |
Definition at line 148 of file RenderTarget.cpp.
| unsigned int sf::RenderImage::GetWidth | ( | ) | const [virtual] |
Return the width of the rendering region of the image.
The returned value is the size that you passed to the Create function.
Implements sf::RenderTarget.
Definition at line 132 of file RenderImage.cpp.
| 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.
Definition at line 212 of file RenderTarget.cpp.
| bool sf::RenderImage::IsAvailable | ( | ) | [static] |
Check whether the system supports render images or not.
It is very important to always call this function before trying to use the RenderImage class, as the feature may not be supported on all platforms (especially very old ones). If this function returns false, then you won't be able to use the class at all.
Definition at line 153 of file RenderImage.cpp.
| bool sf::RenderImage::IsSmooth | ( | ) | const |
Tell whether the smooth filtering is enabled or not.
Definition at line 103 of file RenderImage.cpp.
| 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.
Definition at line 198 of file RenderTarget.cpp.
| 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).
Definition at line 183 of file RenderTarget.cpp.
| bool sf::RenderImage::SetActive | ( | bool | active = true |
) |
Activate of deactivate the render-image for rendering.
This function makes the render-image'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 on 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 |
Definition at line 110 of file RenderImage.cpp.
| void sf::RenderImage::SetSmooth | ( | bool | smooth | ) |
Enable or disable image smoothing.
This function is similar to Image::SetSmooth. This parameter is enabled by default.
| smooth | True to enable smoothing, false to disable it |
Definition at line 96 of file RenderImage.cpp.
| 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 |
Definition at line 125 of file RenderTarget.cpp.