Context Navigation

OgreImage.h

Last change on this file was 148, checked in by patricwi, 7 years ago
Added new dependencies for ogre1.9 and cegui0.8
File size: 19.5 KB

Line
1	/*
2	-----------------------------------------------------------------------------
3	This source file is part of OGRE
4	(Object-oriented Graphics Rendering Engine)
5	For the latest info, see http://www.ogre3d.org/
6
7	Copyright (c) 2000-2013 Torus Knot Software Ltd
8
9	Permission is hereby granted, free of charge, to any person obtaining a copy
10	of this software and associated documentation files (the "Software"), to deal
11	in the Software without restriction, including without limitation the rights
12	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13	copies of the Software, and to permit persons to whom the Software is
14	furnished to do so, subject to the following conditions:
15
16	The above copyright notice and this permission notice shall be included in
17	all copies or substantial portions of the Software.
18
19	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25	THE SOFTWARE.
26	-----------------------------------------------------------------------------
27	*/
28	#ifndef _Image_H__
29	#define _Image_H__
30
31	#include "OgrePrerequisites.h"
32	#include "OgreCommon.h"
33	#include "OgrePixelFormat.h"
34	#include "OgreDataStream.h"
35
36	namespace Ogre {
37	/** \addtogroup Core
38	* @{
39	*/
40	/** \addtogroup Image
41	* @{
42	*/
43
44	enum ImageFlags
45	{
46	IF_COMPRESSED = 0x00000001,
47	IF_CUBEMAP = 0x00000002,
48	IF_3D_TEXTURE = 0x00000004
49	};
50	/** Class representing an image file.
51	@remarks
52	The Image class usually holds uncompressed image data and is the
53	only object that can be loaded in a texture. Image objects handle
54	image data decoding themselves by the means of locating the correct
55	Codec object for each data type.
56	@par
57	Typically, you would want to use an Image object to load a texture
58	when extra processing needs to be done on an image before it is
59	loaded or when you want to blit to an existing texture.
60	*/
61	class _OgreExport Image : public ImageAlloc
62	{
63	public:
64	typedef Ogre::Box Box;
65	typedef Ogre::Rect Rect;
66	public:
67	/** Standard constructor.
68	*/
69	Image();
70	/** Copy-constructor - copies all the data from the target image.
71	*/
72	Image( const Image &img );
73
74	/** Standard destructor.
75	*/
76	virtual ~Image();
77
78	/** Assignment operator - copies all the data from the target image.
79	*/
80	Image & operator = ( const Image & img );
81
82	/** Flips (mirrors) the image around the Y-axis.
83	@remarks
84	An example of an original and flipped image:
85	<pre>
86	originalimg
87	00000000000
88	00000000000
89	00000000000
90	00000000000
91	00000000000
92	------------> flip axis
93	00000000000
94	00000000000
95	00000000000
96	00000000000
97	00000000000
98	originalimg
99	</pre>
100	*/
101	Image & flipAroundY();
102
103	/** Flips (mirrors) the image around the X-axis.
104	@remarks
105	An example of an original and flipped image:
106	<pre>
107	flip axis
108	\|
109	originalimg\|gmilanigiro
110	00000000000\|00000000000
111	00000000000\|00000000000
112	00000000000\|00000000000
113	00000000000\|00000000000
114	00000000000\|00000000000
115	</pre>
116	*/
117	Image & flipAroundX();
118
119	/** Stores a pointer to raw data in memory. The pixel format has to be specified.
120	@remarks
121	This method loads an image into memory held in the object. The
122	pixel format will be either greyscale or RGB with an optional
123	Alpha component.
124	The type can be determined by calling getFormat().
125	@note
126	Whilst typically your image is likely to be a simple 2D image,
127	you can define complex images including cube maps, volume maps,
128	and images including custom mip levels. The layout of the
129	internal memory should be:
130	<ul><li>face 0, mip 0 (top), width x height (x depth)</li>
131	<li>face 0, mip 1, width/2 x height/2 (x depth/2)</li>
132	<li>face 0, mip 2, width/4 x height/4 (x depth/4)</li>
133	<li>.. remaining mips for face 0 .. </li>
134	<li>face 1, mip 0 (top), width x height (x depth)</li
135	<li>.. and so on. </li>
136	</ul>
137	Of course, you will never have multiple faces (cube map) and
138	depth too.
139	@param data
140	The data pointer
141	@param width
142	Width of image
143	@param height
144	Height of image
145	@param depth
146	Image Depth (in 3d images, numbers of layers, otherwise 1)
147	@param format
148	Pixel Format
149	@param autoDelete
150	If memory associated with this buffer is to be destroyed
151	with the Image object. Note: it's important that if you set
152	this option to true, that you allocated the memory using OGRE_ALLOC_T
153	with a category of MEMCATEGORY_GENERAL to ensure the freeing of memory
154	matches up.
155	@param numFaces
156	The number of faces the image data has inside (6 for cubemaps, 1 otherwise)
157	@param numMipMaps
158	The number of mipmaps the image data has inside
159	@note
160	The memory associated with this buffer is NOT destroyed with the
161	Image object, unless autoDelete is set to true.
162	@remarks
163	The size of the buffer must be numFaces*PixelUtil::getMemorySize(width, height, depth, format)
164	*/
165	Image& loadDynamicImage( uchar* data, uint32 width, uint32 height,
166	uint32 depth,
167	PixelFormat format, bool autoDelete = false,
168	size_t numFaces = 1, uint8 numMipMaps = 0);
169
170	/** Stores a pointer to raw data in memory. The pixel format has to be specified.
171	@remarks
172	This method loads an image into memory held in the object. The
173	pixel format will be either greyscale or RGB with an optional
174	Alpha component.
175	The type can be determined by calling getFormat().
176	@note
177	Whilst typically your image is likely to be a simple 2D image,
178	you can define complex images including cube maps
179	and images including custom mip levels. The layout of the
180	internal memory should be:
181	<ul><li>face 0, mip 0 (top), width x height</li>
182	<li>face 0, mip 1, width/2 x height/2 </li>
183	<li>face 0, mip 2, width/4 x height/4 </li>
184	<li>.. remaining mips for face 0 .. </li>
185	<li>face 1, mip 0 (top), width x height (x depth)</li
186	<li>.. and so on. </li>
187	</ul>
188	Of course, you will never have multiple faces (cube map) and
189	depth too.
190	@param data
191	The data pointer
192	@param width
193	Width of image
194	@param height
195	Height of image
196	@param format
197	Pixel Format
198	@note
199	The memory associated with this buffer is NOT destroyed with the
200	Image object.
201	@remarks This function is deprecated; one should really use the
202	Image::loadDynamicImage(data, width, height, depth, format, ...) to be compatible
203	with future Ogre versions.
204	*/
205	Image& loadDynamicImage( uchar* data, uint32 width,
206	uint32 height, PixelFormat format)
207	{
208	return loadDynamicImage(data, width, height, 1, format);
209	}
210	/** Loads raw data from a stream. See the function
211	loadDynamicImage for a description of the parameters.
212	@remarks
213	The size of the buffer must be numFaces*PixelUtil::getMemorySize(width, height, depth, format)
214	@note
215	Whilst typically your image is likely to be a simple 2D image,
216	you can define complex images including cube maps
217	and images including custom mip levels. The layout of the
218	internal memory should be:
219	<ul><li>face 0, mip 0 (top), width x height (x depth)</li>
220	<li>face 0, mip 1, width/2 x height/2 (x depth/2)</li>
221	<li>face 0, mip 2, width/4 x height/4 (x depth/4)</li>
222	<li>.. remaining mips for face 0 .. </li>
223	<li>face 1, mip 0 (top), width x height (x depth)</li
224	<li>.. and so on. </li>
225	</ul>
226	Of course, you will never have multiple faces (cube map) and
227	depth too.
228	*/
229	Image & loadRawData(
230	DataStreamPtr& stream,
231	uint32 width, uint32 height, uint32 depth,
232	PixelFormat format,
233	size_t numFaces = 1, size_t numMipMaps = 0);
234	/** Loads raw data from a stream. The pixel format has to be specified.
235	@remarks This function is deprecated; one should really use the
236	Image::loadRawData(stream, width, height, depth, format, ...) to be compatible
237	with future Ogre versions.
238	@note
239	Whilst typically your image is likely to be a simple 2D image,
240	you can define complex images including cube maps
241	and images including custom mip levels. The layout of the
242	internal memory should be:
243	<ul><li>face 0, mip 0 (top), width x height</li>
244	<li>face 0, mip 1, width/2 x height/2 </li>
245	<li>face 0, mip 2, width/4 x height/4 </li>
246	<li>.. remaining mips for face 0 .. </li>
247	<li>face 1, mip 0 (top), width x height (x depth)</li
248	<li>.. and so on. </li>
249	</ul>
250	Of course, you will never have multiple faces (cube map) and
251	depth too.
252	*/
253	Image & loadRawData(
254	DataStreamPtr& stream,
255	uint32 width, uint32 height,
256	PixelFormat format )
257	{
258	return loadRawData(stream, width, height, 1, format);
259	}
260
261	/** Loads an image file.
262	@remarks
263	This method loads an image into memory. Any format for which
264	an associated ImageCodec is registered can be loaded.
265	This can include complex formats like DDS with embedded custom
266	mipmaps, cube faces and volume textures.
267	The type can be determined by calling getFormat().
268	@param
269	filename Name of an image file to load.
270	@param
271	groupName Name of the resource group to search for the image
272	@note
273	The memory associated with this buffer is destroyed with the
274	Image object.
275	*/
276	Image & load( const String& filename, const String& groupName );
277
278	/** Loads an image file from a stream.
279	@remarks
280	This method works in the same way as the filename-based load
281	method except it loads the image from a DataStream object.
282	This DataStream is expected to contain the
283	encoded data as it would be held in a file.
284	Any format for which an associated ImageCodec is registered
285	can be loaded.
286	This can include complex formats like DDS with embedded custom
287	mipmaps, cube faces and volume textures.
288	The type can be determined by calling getFormat().
289	@param
290	stream The source data.
291	@param
292	type The type of the image. Used to decide what decompression
293	codec to use. Can be left blank if the stream data includes
294	a header to identify the data.
295	@see
296	Image::load( const String& filename )
297	*/
298	Image & load(DataStreamPtr& stream, const String& type = StringUtil::BLANK );
299
300	/** Utility method to combine 2 separate images into this one, with the first
301	image source supplying the RGB channels, and the second image supplying the
302	alpha channel (as luminance or separate alpha).
303	@param rgbFilename Filename of image supplying the RGB channels (any alpha is ignored)
304	@param alphaFilename Filename of image supplying the alpha channel. If a luminance image the
305	single channel is used directly, if an RGB image then the values are
306	converted to greyscale.
307	@param groupName The resource group from which to load the images
308	@param format The destination format
309	*/
310	Image & loadTwoImagesAsRGBA(const String& rgbFilename, const String& alphaFilename,
311	const String& groupName, PixelFormat format = PF_BYTE_RGBA);
312
313	/** Utility method to combine 2 separate images into this one, with the first
314	image source supplying the RGB channels, and the second image supplying the
315	alpha channel (as luminance or separate alpha).
316	@param rgbStream Stream of image supplying the RGB channels (any alpha is ignored)
317	@param alphaStream Stream of image supplying the alpha channel. If a luminance image the
318	single channel is used directly, if an RGB image then the values are
319	converted to greyscale.
320	@param format The destination format
321	@param rgbType The type of the RGB image. Used to decide what decompression
322	codec to use. Can be left blank if the stream data includes
323	a header to identify the data.
324	@param alphaType The type of the alpha image. Used to decide what decompression
325	codec to use. Can be left blank if the stream data includes
326	a header to identify the data.
327	*/
328	Image & loadTwoImagesAsRGBA(DataStreamPtr& rgbStream, DataStreamPtr& alphaStream, PixelFormat format = PF_BYTE_RGBA,
329	const String& rgbType = StringUtil::BLANK, const String& alphaType = StringUtil::BLANK);
330
331	/** Utility method to combine 2 separate images into this one, with the first
332	image source supplying the RGB channels, and the second image supplying the
333	alpha channel (as luminance or separate alpha).
334	@param rgb Image supplying the RGB channels (any alpha is ignored)
335	@param alpha Image supplying the alpha channel. If a luminance image the
336	single channel is used directly, if an RGB image then the values are
337	converted to greyscale.
338	@param format The destination format
339	*/
340	Image & combineTwoImagesAsRGBA(const Image& rgb, const Image& alpha, PixelFormat format = PF_BYTE_RGBA);
341
342
343	/** Save the image as a file.
344	@remarks
345	Saving and loading are implemented by back end (sometimes third
346	party) codecs. Implemented saving functionality is more limited
347	than loading in some cases. Particularly DDS file format support
348	is currently limited to true colour or single channel float32,
349	square, power of two textures with no mipmaps. Volumetric support
350	is currently limited to DDS files.
351	*/
352	void save(const String& filename);
353
354	/** Encode the image and return a stream to the data.
355	@param formatextension An extension to identify the image format
356	to encode into, e.g. "jpg" or "png"
357	*/
358	DataStreamPtr encode(const String& formatextension);
359
360	/** Returns a pointer to the internal image buffer.
361	@remarks
362	Be careful with this method. You will almost certainly
363	prefer to use getPixelBox, especially with complex images
364	which include many faces or custom mipmaps.
365	*/
366	uchar* getData(void);
367
368	/** Returns a const pointer to the internal image buffer.
369	@remarks
370	Be careful with this method. You will almost certainly
371	prefer to use getPixelBox, especially with complex images
372	which include many faces or custom mipmaps.
373	*/
374	const uchar * getData() const;
375
376	/** Returns the size of the data buffer.
377	*/
378	size_t getSize() const;
379
380	/** Returns the number of mipmaps contained in the image.
381	*/
382	uint8 getNumMipmaps() const;
383
384	/** Returns true if the image has the appropriate flag set.
385	*/
386	bool hasFlag(const ImageFlags imgFlag) const;
387
388	/** Gets the width of the image in pixels.
389	*/
390	uint32 getWidth(void) const;
391
392	/** Gets the height of the image in pixels.
393	*/
394	uint32 getHeight(void) const;
395
396	/** Gets the depth of the image.
397	*/
398	uint32 getDepth(void) const;
399
400	/** Get the number of faces of the image. This is usually 6 for a cubemap, and
401	1 for a normal image.
402	*/
403	size_t getNumFaces(void) const;
404
405	/** Gets the physical width in bytes of each row of pixels.
406	*/
407	size_t getRowSpan(void) const;
408
409	/** Returns the image format.
410	*/
411	PixelFormat getFormat() const;
412
413	/** Returns the number of bits per pixel.
414	*/
415	uchar getBPP() const;
416
417	/** Returns true if the image has an alpha component.
418	*/
419	bool getHasAlpha() const;
420
421	/** Does gamma adjustment.
422	@note
423	Basic algo taken from Titan Engine, copyright (c) 2000 Ignacio
424	Castano Iguado
425	*/
426	static void applyGamma( uchar *buffer, Real gamma, size_t size, uchar bpp );
427
428	/**
429	* Get colour value from a certain location in the image. The z coordinate
430	* is only valid for cubemaps and volume textures. This uses the first (largest)
431	* mipmap.
432	*/
433	ColourValue getColourAt(size_t x, size_t y, size_t z) const;
434
435	/**
436	* Set colour value at a certain location in the image. The z coordinate
437	* is only valid for cubemaps and volume textures. This uses the first (largest)
438	* mipmap.
439	*/
440	void setColourAt(ColourValue const &cv, size_t x, size_t y, size_t z);
441
442	/**
443	* Get a PixelBox encapsulating the image data of a mipmap
444	*/
445	PixelBox getPixelBox(size_t face = 0, size_t mipmap = 0) const;
446
447	/// Delete all the memory held by this image, if owned by this image (not dynamic)
448	void freeMemory();
449
450	enum Filter
451	{
452	FILTER_NEAREST,
453	FILTER_LINEAR,
454	FILTER_BILINEAR,
455	FILTER_BOX,
456	FILTER_TRIANGLE,
457	FILTER_BICUBIC
458	};
459	/** Scale a 1D, 2D or 3D image volume.
460	@param src PixelBox containing the source pointer, dimensions and format
461	@param dst PixelBox containing the destination pointer, dimensions and format
462	@param filter Which filter to use
463	@remarks This function can do pixel format conversion in the process.
464	@note dst and src can point to the same PixelBox object without any problem
465	*/
466	static void scale(const PixelBox &src, const PixelBox &dst, Filter filter = FILTER_BILINEAR);
467
468	/** Resize a 2D image, applying the appropriate filter. */
469	void resize(ushort width, ushort height, Filter filter = FILTER_BILINEAR);
470
471	/// Static function to calculate size in bytes from the number of mipmaps, faces and the dimensions
472	static size_t calculateSize(size_t mipmaps, size_t faces, uint32 width, uint32 height, uint32 depth, PixelFormat format);
473
474	/// Static function to get an image type string from a stream via magic numbers
475	static String getFileExtFromMagic(DataStreamPtr stream);
476
477	protected:
478	/// The width of the image in pixels
479	uint32 mWidth;
480	/// The height of the image in pixels
481	uint32 mHeight;
482	/// The depth of the image
483	uint32 mDepth;
484	/// The size of the image buffer
485	size_t mBufSize;
486	/// The number of mipmaps the image contains
487	uint8 mNumMipmaps;
488	/// Image specific flags.
489	int mFlags;
490
491	/// The pixel format of the image
492	PixelFormat mFormat;
493
494	/// The number of bytes per pixel
495	uchar mPixelSize;
496	uchar* mBuffer;
497
498	/// A bool to determine if we delete the buffer or the calling app does
499	bool mAutoDelete;
500	};
501
502	typedef vector<Image*>::type ImagePtrList;
503	typedef vector<const Image*>::type ConstImagePtrList;
504
505	/** @} */
506	/** @} */
507
508	} // namespace
509
510	#endif

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: downloads/ogre_src_v1-9-0/OgreMain/include/OgreImage.h

Download in other formats: