/extlibs/SFML/include/SFML/Graphics/RenderImage.hpp
C++ Header | 289 lines | 31 code | 24 blank | 234 comment | 0 complexity | 54af3b27d3aad99c0bf20bbe27cc043f MD5 | raw file
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////////////////////////////////////////////////////////////