1 ////////////////////////////////////////////////////////////
3 // SFML - Simple and Fast Multimedia Library
4 // Copyright (C) 2007-2013 Laurent Gomila (laurent.gom@gmail.com)
6 // This software is provided 'as-is', without any express or implied warranty.
7 // In no event will the authors be held liable for any damages arising from the use of this software.
9 // Permission is granted to anyone to use this software for any purpose,
10 // including commercial applications, and to alter it and redistribute it freely,
11 // subject to the following restrictions:
13 // 1. The origin of this software must not be misrepresented;
14 // you must not claim that you wrote the original software.
15 // If you use this software in a product, an acknowledgment
16 // in the product documentation would be appreciated but is not required.
18 // 2. Altered source versions must be plainly marked as such,
19 // and must not be misrepresented as being the original software.
21 // 3. This notice may not be removed or altered from any source distribution.
23 ////////////////////////////////////////////////////////////
25 #ifndef SFML_RENDERTARGET_HPP
26 #define SFML_RENDERTARGET_HPP
28 ////////////////////////////////////////////////////////////
30 ////////////////////////////////////////////////////////////
31 #include <SFML/Graphics/Export.hpp>
32 #include <SFML/Graphics/Color.hpp>
33 #include <SFML/Graphics/Rect.hpp>
34 #include <SFML/Graphics/View.hpp>
35 #include <SFML/Graphics/Transform.hpp>
36 #include <SFML/Graphics/BlendMode.hpp>
37 #include <SFML/Graphics/RenderStates.hpp>
38 #include <SFML/Graphics/PrimitiveType.hpp>
39 #include <SFML/Graphics/Vertex.hpp>
40 #include <SFML/System/NonCopyable.hpp>
47 ////////////////////////////////////////////////////////////
48 /// \brief Base class for all render targets (window, texture, ...)
50 ////////////////////////////////////////////////////////////
51 class SFML_GRAPHICS_API RenderTarget : NonCopyable
55 ////////////////////////////////////////////////////////////
58 ////////////////////////////////////////////////////////////
59 virtual ~RenderTarget();
61 ////////////////////////////////////////////////////////////
62 /// \brief Clear the entire target with a single color
64 /// This function is usually called once every frame,
65 /// to clear the previous contents of the target.
67 /// \param color Fill color to use to clear the render target
69 ////////////////////////////////////////////////////////////
70 void clear(const Color& color = Color(0, 0, 0, 255));
72 ////////////////////////////////////////////////////////////
73 /// \brief Change the current active view
75 /// The view is like a 2D camera, it controls which part of
76 /// the 2D scene is visible, and how it is viewed in the
78 /// The new view will affect everything that is drawn, until
79 /// another view is set.
80 /// The render target keeps its own copy of the view object,
81 /// so it is not necessary to keep the original one alive
82 /// after calling this function.
83 /// To restore the original view of the target, you can pass
84 /// the result of getDefaultView() to this function.
86 /// \param view New view to use
88 /// \see getView, getDefaultView
90 ////////////////////////////////////////////////////////////
91 void setView(const View& view);
93 ////////////////////////////////////////////////////////////
94 /// \brief Get the view currently in use in the render target
96 /// \return The view object that is currently used
98 /// \see setView, getDefaultView
100 ////////////////////////////////////////////////////////////
101 const View& getView() const;
103 ////////////////////////////////////////////////////////////
104 /// \brief Get the default view of the render target
106 /// The default view has the initial size of the render target,
107 /// and never changes after the target has been created.
109 /// \return The default view of the render target
111 /// \see setView, getView
113 ////////////////////////////////////////////////////////////
114 const View& getDefaultView() const;
116 ////////////////////////////////////////////////////////////
117 /// \brief Get the viewport of a view, applied to this render target
119 /// The viewport is defined in the view as a ratio, this function
120 /// simply applies this ratio to the current dimensions of the
121 /// render target to calculate the pixels rectangle that the viewport
122 /// actually covers in the target.
124 /// \param view The view for which we want to compute the viewport
126 /// \return Viewport rectangle, expressed in pixels
128 ////////////////////////////////////////////////////////////
129 IntRect getViewport(const View& view) const;
131 ////////////////////////////////////////////////////////////
132 /// \brief Convert a point from target coordinates to world
133 /// coordinates, using the current view
135 /// This function is an overload of the mapPixelToCoords
136 /// function that implicitely uses the current view.
137 /// It is equivalent to:
139 /// target.mapPixelToCoords(point, target.getView());
142 /// \param point Pixel to convert
144 /// \return The converted point, in "world" coordinates
146 /// \see mapCoordsToPixel
148 ////////////////////////////////////////////////////////////
149 Vector2f mapPixelToCoords(const Vector2i& point) const;
151 ////////////////////////////////////////////////////////////
152 /// \brief Convert a point from target coordinates to world coordinates
154 /// This function finds the 2D position that matches the
155 /// given pixel of the render-target. In other words, it does
156 /// the inverse of what the graphics card does, to find the
157 /// initial position of a rendered pixel.
159 /// Initially, both coordinate systems (world units and target pixels)
160 /// match perfectly. But if you define a custom view or resize your
161 /// render-target, this assertion is not true anymore, ie. a point
162 /// located at (10, 50) in your render-target may map to the point
163 /// (150, 75) in your 2D world -- if the view is translated by (140, 25).
165 /// For render-windows, this function is typically used to find
166 /// which point (or object) is located below the mouse cursor.
168 /// This version uses a custom view for calculations, see the other
169 /// overload of the function if you want to use the current view of the
172 /// \param point Pixel to convert
173 /// \param view The view to use for converting the point
175 /// \return The converted point, in "world" units
177 /// \see mapCoordsToPixel
179 ////////////////////////////////////////////////////////////
180 Vector2f mapPixelToCoords(const Vector2i& point, const View& view) const;
182 ////////////////////////////////////////////////////////////
183 /// \brief Convert a point from world coordinates to target
184 /// coordinates, using the current view
186 /// This function is an overload of the mapCoordsToPixel
187 /// function that implicitely uses the current view.
188 /// It is equivalent to:
190 /// target.mapCoordsToPixel(point, target.getView());
193 /// \param point Point to convert
195 /// \return The converted point, in target coordinates (pixels)
197 /// \see mapPixelToCoords
199 ////////////////////////////////////////////////////////////
200 Vector2i mapCoordsToPixel(const Vector2f& point) const;
202 ////////////////////////////////////////////////////////////
203 /// \brief Convert a point from world coordinates to target coordinates
205 /// This function finds the pixel of the render-target that matches
206 /// the given 2D point. In other words, it goes through the same process
207 /// as the graphics card, to compute the final position of a rendered point.
209 /// Initially, both coordinate systems (world units and target pixels)
210 /// match perfectly. But if you define a custom view or resize your
211 /// render-target, this assertion is not true anymore, ie. a point
212 /// located at (150, 75) in your 2D world may map to the pixel
213 /// (10, 50) of your render-target -- if the view is translated by (140, 25).
215 /// This version uses a custom view for calculations, see the other
216 /// overload of the function if you want to use the current view of the
219 /// \param point Point to convert
220 /// \param view The view to use for converting the point
222 /// \return The converted point, in target coordinates (pixels)
224 /// \see mapPixelToCoords
226 ////////////////////////////////////////////////////////////
227 Vector2i mapCoordsToPixel(const Vector2f& point, const View& view) const;
229 ////////////////////////////////////////////////////////////
230 /// \brief Draw a drawable object to the render-target
232 /// \param drawable Object to draw
233 /// \param states Render states to use for drawing
235 ////////////////////////////////////////////////////////////
236 void draw(const Drawable& drawable, const RenderStates& states = RenderStates::Default);
238 ////////////////////////////////////////////////////////////
239 /// \brief Draw primitives defined by an array of vertices
241 /// \param vertices Pointer to the vertices
242 /// \param vertexCount Number of vertices in the array
243 /// \param type Type of primitives to draw
244 /// \param states Render states to use for drawing
246 ////////////////////////////////////////////////////////////
247 void draw(const Vertex* vertices, unsigned int vertexCount,
248 PrimitiveType type, const RenderStates& states = RenderStates::Default);
250 ////////////////////////////////////////////////////////////
251 /// \brief Return the size of the rendering region of the target
253 /// \return Size in pixels
255 ////////////////////////////////////////////////////////////
256 virtual Vector2u getSize() const = 0;
258 ////////////////////////////////////////////////////////////
259 /// \brief Save the current OpenGL render states and matrices
261 /// This function can be used when you mix SFML drawing
262 /// and direct OpenGL rendering. Combined with PopGLStates,
264 /// \li SFML's internal states are not messed up by your OpenGL code
265 /// \li your OpenGL states are not modified by a call to a SFML function
267 /// More specifically, it must be used around code that
268 /// calls Draw functions. Example:
270 /// // OpenGL code here...
271 /// window.pushGLStates();
272 /// window.draw(...);
273 /// window.draw(...);
274 /// window.popGLStates();
275 /// // OpenGL code here...
278 /// Note that this function is quite expensive: it saves all the
279 /// possible OpenGL states and matrices, even the ones you
280 /// don't care about. Therefore it should be used wisely.
281 /// It is provided for convenience, but the best results will
282 /// be achieved if you handle OpenGL states yourself (because
283 /// you know which states have really changed, and need to be
284 /// saved and restored). Take a look at the ResetGLStates
285 /// function if you do so.
289 ////////////////////////////////////////////////////////////
292 ////////////////////////////////////////////////////////////
293 /// \brief Restore the previously saved OpenGL render states and matrices
295 /// See the description of pushGLStates to get a detailed
296 /// description of these functions.
298 /// \see pushGLStates
300 ////////////////////////////////////////////////////////////
303 ////////////////////////////////////////////////////////////
304 /// \brief Reset the internal OpenGL states so that the target is ready for drawing
306 /// This function can be used when you mix SFML drawing
307 /// and direct OpenGL rendering, if you choose not to use
308 /// pushGLStates/popGLStates. It makes sure that all OpenGL
309 /// states needed by SFML are set, so that subsequent draw()
310 /// calls will work as expected.
314 /// // OpenGL code here...
315 /// glPushAttrib(...);
316 /// window.resetGLStates();
317 /// window.draw(...);
318 /// window.draw(...);
319 /// glPopAttrib(...);
320 /// // OpenGL code here...
323 ////////////////////////////////////////////////////////////
324 void resetGLStates();
328 ////////////////////////////////////////////////////////////
329 /// \brief Default constructor
331 ////////////////////////////////////////////////////////////
334 ////////////////////////////////////////////////////////////
335 /// \brief Performs the common initialization step after creation
337 /// The derived classes must call this function after the
338 /// target is created and ready for drawing.
340 ////////////////////////////////////////////////////////////
345 ////////////////////////////////////////////////////////////
346 /// \brief Apply the current view
348 ////////////////////////////////////////////////////////////
349 void applyCurrentView();
351 ////////////////////////////////////////////////////////////
352 /// \brief Apply a new blending mode
354 /// \param mode Blending mode to apply
356 ////////////////////////////////////////////////////////////
357 void applyBlendMode(BlendMode mode);
359 ////////////////////////////////////////////////////////////
360 /// \brief Apply a new transform
362 /// \param transform Transform to apply
364 ////////////////////////////////////////////////////////////
365 void applyTransform(const Transform& transform);
367 ////////////////////////////////////////////////////////////
368 /// \brief Apply a new texture
370 /// \param texture Texture to apply
372 ////////////////////////////////////////////////////////////
373 void applyTexture(const Texture* texture);
375 ////////////////////////////////////////////////////////////
376 /// \brief Apply a new shader
378 /// \param shader Shader to apply
380 ////////////////////////////////////////////////////////////
381 void applyShader(const Shader* shader);
383 ////////////////////////////////////////////////////////////
384 /// \brief Activate the target for rendering
386 /// This function must be implemented by derived classes to make
387 /// their OpenGL context current; it is called by the base class
388 /// everytime it's going to use OpenGL calls.
390 /// \param active True to make the target active, false to deactivate it
392 /// \return True if the function succeeded
394 ////////////////////////////////////////////////////////////
395 virtual bool activate(bool active) = 0;
397 ////////////////////////////////////////////////////////////
398 /// \brief Render states cache
400 ////////////////////////////////////////////////////////////
403 enum {VertexCacheSize = 4};
405 bool glStatesSet; ///< Are our internal GL states set yet?
406 bool viewChanged; ///< Has the current view changed since last draw?
407 BlendMode lastBlendMode; ///< Cached blending mode
408 Uint64 lastTextureId; ///< Cached texture
409 bool useVertexCache; ///< Did we previously use the vertex cache?
410 Vertex vertexCache[VertexCacheSize]; ///< Pre-transformed vertices cache
413 ////////////////////////////////////////////////////////////
415 ////////////////////////////////////////////////////////////
416 View m_defaultView; ///< Default view
417 View m_view; ///< Current view
418 StatesCache m_cache; ///< Render states cache
424 #endif // SFML_RENDERTARGET_HPP
427 ////////////////////////////////////////////////////////////
428 /// \class sf::RenderTarget
429 /// \ingroup graphics
431 /// sf::RenderTarget defines the common behaviour of all the
432 /// 2D render targets usable in the graphics module. It makes
433 /// it possible to draw 2D entities like sprites, shapes, text
434 /// without using any OpenGL command directly.
436 /// A sf::RenderTarget is also able to use views (sf::View),
437 /// which are a kind of 2D cameras. With views you can globally
438 /// scroll, rotate or zoom everything that is drawn,
439 /// without having to transform every single entity. See the
440 /// documentation of sf::View for more details and sample pieces of
441 /// code about this class.
443 /// On top of that, render targets are still able to render direct
444 /// OpenGL stuff. It is even possible to mix together OpenGL calls
445 /// and regular SFML drawing commands. When doing so, make sure that
446 /// OpenGL states are not messed up by calling the
447 /// pushGLStates/popGLStates functions.
449 /// \see sf::RenderWindow, sf::RenderTexture, sf::View
451 ////////////////////////////////////////////////////////////