/extlibs/SFML/include/SFML/Graphics/RenderImage.hpp

  1////////////////////////////////////////////////////////////
  2//
  3// SFML - Simple and Fast Multimedia Library
  4// Copyright (C) 2007-2009 Laurent Gomila (laurent.gom@gmail.com)
  5//
  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.
  8//
  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:
 12//
 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.
 17//
 18// 2. Altered source versions must be plainly marked as such,
 19//    and must not be misrepresented as being the original software.
 20//
 21// 3. This notice may not be removed or altered from any source distribution.
 22//
 23////////////////////////////////////////////////////////////
 24
 25#ifndef SFML_RENDERIMAGE_HPP
 26#define SFML_RENDERIMAGE_HPP
 27
 28////////////////////////////////////////////////////////////
 29// Headers
 30////////////////////////////////////////////////////////////
 31#include <SFML/Graphics/Image.hpp>
 32#include <SFML/Graphics/RenderTarget.hpp>
 33
 34
 35namespace sf
 36{
 37namespace priv
 38{
 39    class RenderImageImpl;
 40}
 41
 42////////////////////////////////////////////////////////////
 43/// \brief Target for off-screen 2D rendering into an image
 44///
 45////////////////////////////////////////////////////////////
 46class SFML_API RenderImage : public RenderTarget
 47{
 48public :
 49
 50    ////////////////////////////////////////////////////////////
 51    /// \brief Default constructor
 52    ///
 53    /// Constructs an empty, invalid render-image. You must
 54    /// call Create to have a valid render-image.
 55    ///
 56    /// \see Create
 57    ///
 58    ////////////////////////////////////////////////////////////
 59    RenderImage();
 60
 61    ////////////////////////////////////////////////////////////
 62    /// \brief Destructor
 63    ///
 64    ////////////////////////////////////////////////////////////
 65    virtual ~RenderImage();
 66
 67    ////////////////////////////////////////////////////////////
 68    /// \brief Create the render-image
 69    ///
 70    /// Before calling this function, the render-image is in
 71    /// an invalid state, thus it is mandatory to call it before
 72    /// doing anything with the render-image.
 73    /// The last parameter, \a depthBuffer, is useful if you want
 74    /// to use the render-image for 3D OpenGL rendering that requires
 75    /// a depth-buffer. Otherwise it is unnecessary, and you should
 76    /// leave this parameter to false (which is its default value).
 77    ///
 78    /// \param width        Width of the render-image
 79    /// \param height       Height of the render-image
 80    /// \param depthBuffer  Do you want this render-image to have a depth buffer?
 81    ///
 82    /// \return True if creation has been successful
 83    ///
 84    ////////////////////////////////////////////////////////////
 85    bool Create(unsigned int width, unsigned int height, bool depthBuffer = false);
 86
 87    ////////////////////////////////////////////////////////////
 88    /// \brief Enable or disable image smoothing
 89    ///
 90    /// This function is similar to Image::SetSmooth.
 91    /// This parameter is enabled by default.
 92    ///
 93    /// \param smooth True to enable smoothing, false to disable it
 94    ///
 95    /// \see IsSmooth
 96    ///
 97    ////////////////////////////////////////////////////////////
 98    void SetSmooth(bool smooth);
 99
100    ////////////////////////////////////////////////////////////
101    /// \brief Tell whether the smooth filtering is enabled or not
102    ///
103    /// \return True if image smoothing is enabled
104    ///
105    /// \see SetSmooth
106    ///
107    ////////////////////////////////////////////////////////////
108    bool IsSmooth() const;
109
110    ////////////////////////////////////////////////////////////
111    /// \brief Activate of deactivate the render-image for rendering
112    ///
113    /// This function makes the render-image's context current for
114    /// future OpenGL rendering operations (so you shouldn't care
115    /// about it if you're not doing direct OpenGL stuff).
116    /// Only one context can be current on a thread, so if you
117    /// want to draw OpenGL geometry to another render target
118    /// (like a RenderWindow) don't forget to activate it again.
119    ///
120    /// \param active True to activate, false to deactivate
121    ///
122    /// \return True if operation was successful, false otherwise
123    ///
124    ////////////////////////////////////////////////////////////
125    bool SetActive(bool active = true);
126
127    ////////////////////////////////////////////////////////////
128    /// \brief Update the contents of the target image
129    ///
130    /// This function updates the target image with what
131    /// has been drawn so far. Like for windows, calling this
132    /// function is mandatory at the end of rendering. Not calling
133    /// it may leave the image in an undefined state.
134    ///
135    ////////////////////////////////////////////////////////////
136    void Display();
137
138    ////////////////////////////////////////////////////////////
139    /// \brief Return the width of the rendering region of the image
140    ///
141    /// The returned value is the size that you passed to
142    /// the Create function.
143    ///
144    /// \return Width in pixels
145    ///
146    /// \return GetHeight
147    ///
148    ////////////////////////////////////////////////////////////
149    virtual unsigned int GetWidth() const;
150
151    ////////////////////////////////////////////////////////////
152    /// \brief Return the height of the rendering region of the image
153    ///
154    /// The returned value is the size that you passed to
155    /// the Create function.
156    ///
157    /// \return Height in pixels
158    ///
159    /// \return GetWidth
160    ///
161    ////////////////////////////////////////////////////////////
162    virtual unsigned int GetHeight() const;
163
164    ////////////////////////////////////////////////////////////
165    /// \brief Get a read-only reference to the target image
166    ///
167    /// After drawing to the render-image and calling Display,
168    /// you can retrieve the updated image using this function,
169    /// and draw it using a sprite (for example).
170    /// The internal sf::Image of a render-image is always the
171    /// same instance, so that it is possible to call this function
172    /// once and keep a reference to the image even after is it
173    /// modified.
174    ///
175    /// \return Const reference to the image
176    ///
177    ////////////////////////////////////////////////////////////
178    const Image& GetImage() const;
179
180    ////////////////////////////////////////////////////////////
181    /// \brief Check whether the system supports render images or not
182    ///
183    /// It is very important to always call this function before
184    /// trying to use the RenderImage class, as the feature may not
185    /// be supported on all platforms (especially very old ones).
186    /// If this function returns false, then you won't be able
187    /// to use the class at all.
188    ///
189    /// \return True if the RenderImage class can be used
190    ///
191    ////////////////////////////////////////////////////////////
192    static bool IsAvailable();
193
194private :
195
196    ////////////////////////////////////////////////////////////
197    /// \brief Activate the targt efor rendering
198    ///
199    /// This function is called by the base class
200    /// everytime it's going to use OpenGL calls.
201    ///
202    /// \param active True to make the target active, false to deactivate it
203    ///
204    /// \return True if the function succeeded
205    ///
206    ////////////////////////////////////////////////////////////
207    virtual bool Activate(bool active);
208
209    ////////////////////////////////////////////////////////////
210    // Member data
211    ////////////////////////////////////////////////////////////
212    Image                  myImage;       ///< Target image to draw on
213    priv::RenderImageImpl* myRenderImage; ///< Platform / hardware specific implementation
214};
215
216} // namespace sf
217
218
219#endif // SFML_RENDERIMAGE_HPP
220
221
222////////////////////////////////////////////////////////////
223/// \class sf::RenderImage
224/// \ingroup graphics
225///
226/// sf::RenderImage is the little brother of sf::RenderWindow.
227/// It implements the same 2D drawing and OpenGL-related functions
228/// (see their base class sf::RenderTarget for more details),
229/// the difference is that the result is stored in an off-screen
230/// image rather than being show in a window.
231///
232/// Rendering to an image can be useful in a variety of situations:
233/// \li precomputing a complex static image (like a level's background from multiple tiles)
234/// \li applying post-effects to the whole scene with shaders
235/// \li creating a sprite from a 3D object rendered with OpenGL
236/// \li etc.
237///
238/// Usage example:
239///
240/// \code
241/// // First of all: make sure that rendering to image is supported
242/// if (!sf::RenderImage::IsAvailable())
243///    return -1;
244///
245/// // Create a new render-window
246/// sf::RenderWindow window(sf::VideoMode(800, 600), "SFML window");
247///
248/// // Create a new render-image
249/// sf::RenderImage image;
250/// if (!image.Create(500, 500))
251///     return -1
252///
253/// // The main loop
254/// while (window.IsOpened())
255/// {
256///    // Event processing
257///    // ...
258///
259///    // Clear the whole image with red color
260///    image.Clear(sf::Color::Red);
261///
262///    // Draw stuff to the image
263///    image.Draw(sprite);  // sprite is a sf::Sprite
264///    image.Draw(shape);   // shape is a sf::Shape
265///    image.Draw(text);    // text is a sf::Text
266///
267///    // We're done drawing to the image
268///    image.Display();
269///
270///    // Now we start rendering to the window, clear it first
271///    window.Clear();
272///
273///    // Draw the image
274///    sf::Sprite sprite(image.GetImage());
275///    window.Draw(sprite);
276///
277///    // End the current frame and display its contents on screen
278///    window.Display();
279/// }
280/// \endcode
281///
282/// Like sf::RenderWindow, sf::RenderImage is still able to render direct
283/// OpenGL stuff. It is even possible to mix together OpenGL calls
284/// and regular SFML drawing commands. If you need a depth buffer for
285/// 3D rendering, don't forget to request it when calling RenderImage::Create.
286///
287/// \see sf::RenderTarget, sf::RenderWindow, sf::View
288///
289////////////////////////////////////////////////////////////