Spinning Topp Logo BlackTopp Studios
inc
texturebuffer.h
1 // © Copyright 2010 - 2016 BlackTopp Studios Inc.
2 /* This file is part of The Mezzanine Engine.
3 
4  The Mezzanine Engine is free software: you can redistribute it and/or modify
5  it under the terms of the GNU General Public License as published by
6  the Free Software Foundation, either version 3 of the License, or
7  (at your option) any later version.
8 
9  The Mezzanine Engine is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  GNU General Public License for more details.
13 
14  You should have received a copy of the GNU General Public License
15  along with The Mezzanine Engine. If not, see <http://www.gnu.org/licenses/>.
16 */
17 /* The original authors have included a copy of the license specified above in the
18  'Docs' folder. See 'gpl.txt'
19 */
20 /* We welcome the use of the Mezzanine engine to anyone, including companies who wish to
21  Build professional software and charge for their product.
22 
23  However there are some practical restrictions, so if your project involves
24  any of the following you should contact us and we will try to work something
25  out:
26  - DRM or Copy Protection of any kind(except Copyrights)
27  - Software Patents You Do Not Wish to Freely License
28  - Any Kind of Linking to Non-GPL licensed Works
29  - Are Currently In Violation of Another Copyright Holder's GPL License
30  - If You want to change our code and not add a few hundred MB of stuff to
31  your distribution
32 
33  These and other limitations could cause serious legal problems if you ignore
34  them, so it is best to simply contact us or the Free Software Foundation, if
35  you have any questions.
36 
37  Joseph Toppi - toppij@gmail.com
38  John Blackwood - makoenergy02@gmail.com
39 */
40 /*
41  -----------------------------------------------------------------------------
42  This source file is part of ogre-procedural
43 
44  For the latest info, see http://code.google.com/p/ogre-procedural/
45 
46  Copyright (c) 2010-2013 Michael Broutin
47 
48  Permission is hereby granted, free of charge, to any person obtaining a copy
49  of this software and associated documentation files (the "Software"), to deal
50  in the Software without restriction, including without limitation the rights
51  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
52  copies of the Software, and to permit persons to whom the Software is
53  furnished to do so, subject to the following conditions:
54 
55  The above copyright notice and this permission notice shall be included in
56  all copies or substantial portions of the Software.
57 
58  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
59  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
60  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
61  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
62  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
63  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
64  THE SOFTWARE.
65  -----------------------------------------------------------------------------
66  */
67 #ifndef _graphicsproceduraltexturebuffer_h
68 #define _graphicsproceduraltexturebuffer_h
69 
70 #include "colourvalue.h"
71 #include "Graphics/graphicsenumerations.h"
72 
73 namespace Mezzanine
74 {
75  namespace Graphics
76  {
77  class Image;
78  class Texture;
79  namespace Procedural
80  {
81  ///////////////////////////////////////////////////////////////////////////////
82  /// @brief A convenience buffer that stores pixel colour values of a texture to be generated.
83  /// @details
84  /// @todo Verify byte order and endian-ness isn't an issue on all supported platforms.
85  ///////////////////////////////////////
86  class MEZZ_LIB TextureBuffer
87  {
88  public:
89  /// @brief Convenience typedef for the datatype containing the value for each colour channel.
90  typedef UInt8 ColourChannelType;
91  protected:
92  /// @internal
93  /// @brief A pointer to the buffer storing all the pixels of this texture buffer.
94  ColourChannelType* Pixels;
95  /// @internal
96  /// @brief The size of the texture to be generated on the X axis.
97  Whole Width;
98  /// @internal
99  /// @brief The size of the texture to be generated on the Y axis.
100  Whole Height;
101 
102  /// @internal
103  /// @brief Gets access to the pixel at the specified position in this buffer.
104  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
105  /// @param X The X position of the pixel to access.
106  /// @param Y The Y position of the pixel to access.
107  /// @param Component The colour component to access.
108  /// @return Returns a ColourChannelType reference to the requested component of the requested pixel.
109  ColourChannelType& GetPixel(const Whole X, const Whole Y, const UInt16 Component);
110  /// @internal
111  /// @brief Gets access to the pixel at the specified position in this buffer.
112  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
113  /// @param X The X position of the pixel to access.
114  /// @param Y The Y position of the pixel to access.
115  /// @param Component The colour component to access.
116  /// @return Returns a const ColourChannelType reference to the requested component of the requested pixel.
117  const ColourChannelType& GetPixel(const Whole X, const Whole Y, const UInt16 Component) const;
118  public:
119  /// @brief Square size constructor.
120  /// @param SquareSize The width and height of the texture to create. This value will be clamped to be at least 8.
121  TextureBuffer(const Whole SquareSize);
122  /// @brief Size dimensions constructor.
123  /// @param TexWidth The pixel width of the texture to create. This value will be clamped to be at least 8.
124  /// @param TexHeight The pixel height of the texture to create. This value will be clamped to be at least 8.
125  TextureBuffer(const Whole TexWidth, const Whole TexHeight);
126  /// @brief Copy constructor.
127  /// @param Other The other TextureBuffer to be copied.
128  TextureBuffer(const TextureBuffer& Other);
129  /// @brief Class destructor.
130  ~TextureBuffer();
131 
132  ///////////////////////////////////////////////////////////////////////////////
133  // Utility
134 
135  /// @brief Copies image data from another buffer into this buffer.
136  /// @param Other The other TextureBuffer that will having it's contents copied to this.
137  void SetData(const TextureBuffer& Other);
138 
139  /// @brief Get the pixel width of this texture.
140  /// @return Returns a Whole representing the width of this TextureBuffer in pixels.
141  Whole GetWidth() const;
142  /// @brief Get the pixel height of this texture.
143  /// @return Returns a Whole representing the height of this TextureBuffer in pixels.
144  Whole GetHeight() const;
145 
146  /// @brief Gets the number of pixels in this texture.
147  /// @return Returns the total number of pixels in this texture (width * height).
148  Whole GetPixelCount() const;
149  /// @brief Gets the number of colour channels among all the pixels in this texture.
150  /// @return Returns the total number of colour channels in this texture (PixelCount * 4).
151  Whole GetSubChannelCount() const;
152  /// @brief Gets the size of the internal buffer in bytes.
153  /// @return Returns the size of the buffer containing the pixels of the image in bytes.
154  Whole GetByteSize() const;
155 
156  /// @brief Creates an Image from this buffer.
157  /// @remarks The generated image is not owned by this buffer or anything. It is up to the user/caller of this method to clean it up.
158  /// @param Format The pixel format for the generated Image. Defaults to: Graphics::PF_R8G8B8A8 (Ideal for PNG).
159  /// @return Returns a pointer to the converted Image.
160  Image* GenerateImage(const Graphics::PixelFormat Format = Graphics::PF_R8G8B8A8) const;
161  /// @brief Creates a Texture from this buffer.
162  /// @param TexName The name of the Texture to be generated.
163  /// @param TexGroup The name of the resource group to create the Texture in.
164  /// @param Format The pixel format for the generated Texture. Defaults to: Graphics::PF_R8G8B8A8 (Ideal for PNG).
165  /// @return Returns a pointer to the converted Texture.
166  Texture* GenerateTexture(const String& TexName, const String& TexGroup, const Graphics::PixelFormat Format = Graphics::PF_R8G8B8A8) const;
167 
168  ///////////////////////////////////////////////////////////////////////////////
169  // Pixel Configuration
170 
171  /// @brief Set colour of a specified pixel using a ColourValue.
172  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
173  /// @param X The X position of pixel to change the colour of.
174  /// @param Y The Y position of pixel to change the colour of.
175  /// @param Colour The colour to be applied to the specified pixel.
176  void SetPixel(const Whole X, const Whole Y, const ColourValue& Colour);
177  /// @brief Set colour of a specified pixel using a 0-255 range.
178  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
179  /// @param X The X position of pixel to change the colour of.
180  /// @param Y The Y position of pixel to change the colour of.
181  /// @param Red The amount of Red colour to be applied to the specified pixel. Range: [0, 255].
182  /// @param Green The amount of Green colour to be applied to the specified pixel. Range: [0, 255].
183  /// @param Blue The amount of Blue colour to be applied to the specified pixel. Range: [0, 255].
184  /// @param Alpha The amount of Alpha colour to be applied to the specified pixel. Range: [0, 255].
185  void SetPixelByte(const Whole X, const Whole Y, const ColourChannelType Red, const ColourChannelType Green, const ColourChannelType Blue, const ColourChannelType Alpha = 255);
186  /// @brief Set colour of a specified pixel using a 0.0-1.0 range.
187  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
188  /// @exception If any of the colour values passed in are outside of the range of 0.0-1.0, then a PARAMETERS_RANGE_EXCEPTION will be thrown.
189  /// @param X The X position of pixel to change the colour of.
190  /// @param Y The Y position of pixel to change the colour of.
191  /// @param Red The amount of Red colour to be applied to the specified pixel. Range: [0.0, 1.0].
192  /// @param Green The amount of Green colour to be applied to the specified pixel. Range: [0.0, 1.0].
193  /// @param Blue The amount of Blue colour to be applied to the specified pixel. Range: [0.0, 1.0].
194  /// @param Alpha The amount of Alpha colour to be applied to the specified pixel. Range: [0.0, 1.0].
195  void SetPixelReal(const Whole X, const Whole Y, const Real Red, const Real Green, const Real Blue, const Real Alpha = 1.0);
196  /// @brief Get the colour of a pixel at the specified point.
197  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
198  /// @param X The X position of pixel to retrieve.
199  /// @param Y The Y position of pixel to retrieve.
200  /// @return Returns a ColourValue containing the colour of the specified pixel.
201  ColourValue GetPixel(const Whole X, const Whole Y) const;
202 
203  /// @brief Sets the red colour value of a specified pixel.
204  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
205  /// @param X The X position of pixel to change the colour of.
206  /// @param Y The Y position of pixel to change the colour of.
207  /// @param Red The amount of red colour to be applied to the specified pixel. Range: [0, 255].
208  void SetRedByte(const Whole X, const Whole Y, const ColourChannelType Red);
209  /// @brief Sets the red colour value of a specified pixel.
210  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
211  /// @exception If any of the colour values passed in are outside of the range of 0.0-1.0, then a PARAMETERS_RANGE_EXCEPTION will be thrown.
212  /// @param X The X position of pixel to change the colour of.
213  /// @param Y The Y position of pixel to change the colour of.
214  /// @param Red The amount of red colour to be applied to the specified pixel. Range: [0.0, 1.0].
215  void SetRedReal(const Whole X, const Whole Y, const Real Red);
216  /// @brief Gets the red colour value of a specified pixel.
217  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
218  /// @param X The X position of pixel to retrieve.
219  /// @param Y The Y position of pixel to retrieve.
220  /// @return Returns a ColourChannelType representing the red component of the colour in the specified pixel. Range: [0, 255].
221  ColourChannelType GetRedByte(const Whole X, const Whole Y) const;
222  /// @brief Gets the red colour value of a specified pixel.
223  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
224  /// @param X The X position of pixel to retrieve.
225  /// @param Y The Y position of pixel to retrieve.
226  /// @return Returns a Real representing the red component of the colour in the specified pixel. Range: [0.0, 1.0].
227  Real GetRedReal(const Whole X, const Whole Y) const;
228 
229  /// @brief Sets the green colour value of a specified pixel.
230  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
231  /// @param X The X position of pixel to change the colour of.
232  /// @param Y The Y position of pixel to change the colour of.
233  /// @param Green The amount of green colour to be applied to the specified pixel. Range: [0, 255].
234  void SetGreenByte(const Whole X, const Whole Y, const ColourChannelType Green);
235  /// @brief Sets the green colour value of a specified pixel.
236  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
237  /// @exception If any of the colour values passed in are outside of the range of 0.0-1.0, then a PARAMETERS_RANGE_EXCEPTION will be thrown.
238  /// @param X The X position of pixel to change the colour of.
239  /// @param Y The Y position of pixel to change the colour of.
240  /// @param Green The amount of green colour to be applied to the specified pixel. Range: [0.0, 1.0].
241  void SetGreenReal(const Whole X, const Whole Y, const Real Green);
242  /// @brief Gets the green colour value of a specified pixel.
243  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
244  /// @param X The X position of pixel to retrieve.
245  /// @param Y The Y position of pixel to retrieve.
246  /// @return Returns a ColourChannelType representing the green component of the colour in the specified pixel. Range: [0, 255].
247  ColourChannelType GetGreenByte(const Whole X, const Whole Y) const;
248  /// @brief Gets the green colour value of a specified pixel.
249  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
250  /// @param X The X position of pixel to retrieve.
251  /// @param Y The Y position of pixel to retrieve.
252  /// @return Returns a Real representing the green component of the colour in the specified pixel. Range: [0.0, 1.0].
253  Real GetGreenReal(const Whole X, const Whole Y) const;
254 
255  /// @brief Sets the blue colour value of a specified pixel.
256  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
257  /// @param X The X position of pixel to change the colour of.
258  /// @param Y The Y position of pixel to change the colour of.
259  /// @param Blue The amount of blue colour to be applied to the specified pixel. Range: [0, 255].
260  void SetBlueByte(const Whole X, const Whole Y, const ColourChannelType Blue);
261  /// @brief Sets the blue colour value of a specified pixel.
262  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
263  /// @exception If any of the colour values passed in are outside of the range of 0.0-1.0, then a PARAMETERS_RANGE_EXCEPTION will be thrown.
264  /// @param X The X position of pixel to change the colour of.
265  /// @param Y The Y position of pixel to change the colour of.
266  /// @param Blue The amount of blue colour to be applied to the specified pixel. Range: [0.0, 1.0].
267  void SetBlueReal(const Whole X, const Whole Y, const Real Blue);
268  /// @brief Gets the blue colour value of a specified pixel.
269  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
270  /// @param X The X position of pixel to retrieve.
271  /// @param Y The Y position of pixel to retrieve.
272  /// @return Returns a ColourChannelType representing the blue component of the colour in the specified pixel. Range: [0, 255].
273  ColourChannelType GetBlueByte(const Whole X, const Whole Y) const;
274  /// @brief Gets the blue colour value of a specified pixel.
275  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
276  /// @param X The X position of pixel to retrieve.
277  /// @param Y The Y position of pixel to retrieve.
278  /// @return Returns a Real representing the blue component of the colour in the specified pixel. Range: [0.0, 1.0].
279  Real GetBlueReal(const Whole X, const Whole Y) const;
280 
281  /// @brief Sets the alpha colour value of a specified pixel.
282  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
283  /// @param X The X position of pixel to change the colour of.
284  /// @param Y The Y position of pixel to change the colour of.
285  /// @param Alpha The amount of alpha colour to be applied to the specified pixel. Range: [0, 255].
286  void SetAlphaByte(const Whole X, const Whole Y, const ColourChannelType Alpha);
287  /// @brief Sets the alpha colour value of a specified pixel.
288  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
289  /// @exception If any of the colour values passed in are outside of the range of 0.0-1.0, then a PARAMETERS_RANGE_EXCEPTION will be thrown.
290  /// @param X The X position of pixel to change the colour of.
291  /// @param Y The Y position of pixel to change the colour of.
292  /// @param Alpha The amount of alpha colour to be applied to the specified pixel. Range: [0.0, 1.0].
293  void SetAlphaReal(const Whole X, const Whole Y, const Real Alpha);
294  /// @brief Gets the alpha colour value of a specified pixel.
295  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
296  /// @param X The X position of pixel to retrieve.
297  /// @param Y The Y position of pixel to retrieve.
298  /// @return Returns a ColourChannelType representing the alpha component of the colour in the specified pixel. Range: [0, 255].
299  ColourChannelType GetAlphaByte(const Whole X, const Whole Y) const;
300  /// @brief Gets the alpha colour value of a specified pixel.
301  /// @exception If the X or Y location go beyond the set size of this texture buffer, then a MM_OUT_OF_BOUNDS_EXCEPTION will be thrown.
302  /// @param X The X position of pixel to retrieve.
303  /// @param Y The Y position of pixel to retrieve.
304  /// @return Returns a Real representing the alpha component of the colour in the specified pixel. Range: [0.0, 1.0].
305  Real GetAlphaReal(const Whole X, const Whole Y) const;
306  };//TextureBuffer
307 
308  ///////////////////////////////////////////////////////////////////////////////
309  /// @brief Convenience class for pixel processing.
310  /// @details
311  ///////////////////////////////////////
312  struct IntVector2
313  {
314  /// @brief Position on the X axis.
315  Whole X;
316  /// @brief Position on the Y axis.
317  Whole Y;
318  };//IntVector2
319  }//Procedural
320  }//Graphics
321 }//Mezzanine
322 
323 #endif
Mezzanine::Graphics::Procedural::TextureBuffer::Height
Whole Height
The size of the texture to be generated on the Y axis.
Definition: texturebuffer.h:100
Mezzanine::Graphics::Procedural::TextureBuffer::Width
Whole Width
The size of the texture to be generated on the X axis.
Definition: texturebuffer.h:97
Mezzanine::UInt8
uint8_t UInt8
An 8-bit unsigned integer.
Definition: datatypes.h:118
Mezzanine::ColourValue
This is a simple class for holding 4 reals representing the colour any give object or lightsource can...
Definition: colourvalue.h:64
Mezzanine::Graphics::Procedural::TextureBuffer::Pixels
ColourChannelType * Pixels
A pointer to the buffer storing all the pixels of this texture buffer.
Definition: texturebuffer.h:94
Mezzanine::Real
float Real
A Datatype used to represent a real floating point number.
Definition: datatypes.h:141
Mezzanine::UInt16
uint16_t UInt16
An 16-bit unsigned integer.
Definition: datatypes.h:122
Mezzanine::Graphics::Procedural::IntVector2
Convenience class for pixel processing.
Definition: texturebuffer.h:312
Mezzanine::Graphics::Texture
This class represents a texture loaded into video memory.
Definition: texture.h:63
Mezzanine::Graphics::Image
This class represents an image loaded into system memory.
Definition: image.h:63
Mezzanine::Graphics::PixelFormat
PixelFormat
This is used to describe how bits are arraged for each pixel in an image.
Definition: graphicsenumerations.h:189
Mezzanine::Graphics::Procedural::TextureBuffer
A convenience buffer that stores pixel colour values of a texture to be generated.
Definition: texturebuffer.h:86
MEZZ_LIB
#define MEZZ_LIB
Some platforms require special decorations to denote what is exported/imported in a share library...
Definition: crossplatformexport.h:139
Mezzanine
The bulk of the engine components go in this namspace.
Definition: actor.cpp:56
Mezzanine::Whole
unsigned long Whole
Whole is an unsigned integer, it will be at least 32bits in size.
Definition: datatypes.h:151
Mezzanine::String
std::string String
A datatype used to a series of characters.
Definition: datatypes.h:159
Mezzanine::Graphics::Procedural::TextureBuffer::ColourChannelType
UInt8 ColourChannelType
Convenience typedef for the datatype containing the value for each colour channel.
Definition: texturebuffer.h:90
Generated on Wed Apr 6 2016 08:34:46 for BlackTopp Studios inc by doxygen 1.8.9.1. Thanks to the Open Icon Library for help with some of the icons.