Context Navigation

← Previous Revision
Latest Revision
Next Revision →
Blame
Revision Log

OgreImage.h @ 29

Last change on this file since 29 was 5, checked in by anonymous, 18 years ago
=hoffentlich gehts jetzt
File size: 15.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-2006 Torus Knot Software Ltd
8	Also see acknowledgements in Readme.html
9
10	This program is free software; you can redistribute it and/or modify it under
11	the terms of the GNU Lesser General Public License as published by the Free Software
12	Foundation; either version 2 of the License, or (at your option) any later
13	version.
14
15	This program is distributed in the hope that it will be useful, but WITHOUT
16	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17	FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19	You should have received a copy of the GNU Lesser General Public License along with
20	this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21	Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22	http://www.gnu.org/copyleft/lesser.txt.
23
24	You may alternatively use this source under the terms of a specific version of
25	the OGRE Unrestricted License provided you have obtained such a license from
26	Torus Knot Software Ltd.
27	-----------------------------------------------------------------------------
28	*/
29	#ifndef _Image_H__
30	#define _Image_H__
31
32	#include "OgrePrerequisites.h"
33	#include "OgreCommon.h"
34	#include "OgrePixelFormat.h"
35	#include "OgreDataStream.h"
36
37	namespace Ogre {
38
39	enum ImageFlags
40	{
41	IF_COMPRESSED = 0x00000001,
42	IF_CUBEMAP = 0x00000002,
43	IF_3D_TEXTURE = 0x00000004
44	};
45	/** Class representing an image file.
46	@remarks
47	The Image class usually holds uncompressed image data and is the
48	only object that can be loaded in a texture. Image objects handle
49	image data decoding themselves by the means of locating the correct
50	Codec object for each data type.
51	@par
52	Typically, you would want to use an Image object to load a texture
53	when extra processing needs to be done on an image before it is
54	loaded or when you want to blit to an existing texture.
55	*/
56	class _OgreExport Image
57	{
58	public:
59	typedef Ogre::Box Box;
60	typedef Ogre::Rect Rect;
61	public:
62	/** Standard constructor.
63	*/
64	Image();
65	/** Copy-constructor - copies all the data from the target image.
66	*/
67	Image( const Image &img );
68
69	/** Standard destructor.
70	*/
71	virtual ~Image();
72
73	/** Assignment operator - copies all the data from the target image.
74	*/
75	Image & operator = ( const Image & img );
76
77	/** Flips (mirrors) the image around the Y-axis.
78	@remarks
79	An example of an original and flipped image:
80	<pre>
81	originalimg
82	00000000000
83	00000000000
84	00000000000
85	00000000000
86	00000000000
87	------------> flip axis
88	00000000000
89	00000000000
90	00000000000
91	00000000000
92	00000000000
93	originalimg
94	</pre>
95	*/
96	Image & flipAroundY();
97
98	/** Flips (mirrors) the image around the X-axis.
99	@remarks
100	An example of an original and flipped image:
101	<pre>
102	flip axis
103	\|
104	originalimg\|gmilanigiro
105	00000000000\|00000000000
106	00000000000\|00000000000
107	00000000000\|00000000000
108	00000000000\|00000000000
109	00000000000\|00000000000
110	</pre>
111	*/
112	Image & flipAroundX();
113
114	/** Stores a pointer to raw data in memory. The pixel format has to be specified.
115	@remarks
116	This method loads an image into memory held in the object. The
117	pixel format will be either greyscale or RGB with an optional
118	Alpha component.
119	The type can be determined by calling getFormat().
120	@note
121	Whilst typically your image is likely to be a simple 2D image,
122	you can define complex images including cube maps, volume maps,
123	and images including custom mip levels. The layout of the
124	internal memory should be:
125	<ul><li>face 0, mip 0 (top), width x height (x depth)</li>
126	<li>face 0, mip 1, width/2 x height/2 (x depth/2)</li>
127	<li>face 0, mip 2, width/4 x height/4 (x depth/4)</li>
128	<li>.. remaining mips for face 0 .. </li>
129	<li>face 1, mip 0 (top), width x height (x depth)</li
130	<li>.. and so on. </li>
131	</ul>
132	Of course, you will never have multiple faces (cube map) and
133	depth too.
134	@param
135	The data pointer
136	@param
137	Width of image
138	@param
139	Height of image
140	@param
141	Image Depth (in 3d images, numbers of layers, otherwhise 1)
142	@param
143	Pixel Format
144	@param
145	if memory associated with this buffer is to be destroyed
146	with the Image object.
147	@param
148	the number of faces the image data has inside (6 for cubemaps, 1 otherwise)
149	@param
150	the number of mipmaps the image data has inside
151	@note
152	The memory associated with this buffer is NOT destroyed with the
153	Image object, unless autoDelete is set to true.
154	@remarks
155	The size of the buffer must be numFaces*PixelUtil::getMemorySize(width, height, depth, format)
156	*/
157	Image& loadDynamicImage( uchar* pData, size_t uWidth, size_t uHeight,
158	size_t depth,
159	PixelFormat eFormat, bool autoDelete = false,
160	size_t numFaces = 1, size_t numMipMaps = 0);
161
162	/** Stores a pointer to raw data in memory. The pixel format has to be specified.
163	@remarks
164	This method loads an image into memory held in the object. The
165	pixel format will be either greyscale or RGB with an optional
166	Alpha component.
167	The type can be determined by calling getFormat().
168	@note
169	Whilst typically your image is likely to be a simple 2D image,
170	you can define complex images including cube maps
171	and images including custom mip levels. The layout of the
172	internal memory should be:
173	<ul><li>face 0, mip 0 (top), width x height</li>
174	<li>face 0, mip 1, width/2 x height/2 </li>
175	<li>face 0, mip 2, width/4 x height/4 </li>
176	<li>.. remaining mips for face 0 .. </li>
177	<li>face 1, mip 0 (top), width x height (x depth)</li
178	<li>.. and so on. </li>
179	</ul>
180	Of course, you will never have multiple faces (cube map) and
181	depth too.
182	@param
183	The data pointer
184	@param
185	Width of image
186	@param
187	Height of image
188	@param
189	Pixel Format
190	@note
191	The memory associated with this buffer is NOT destroyed with the
192	Image object.
193	@remarks This function is deprecated; one should really use the
194	Image::loadDynamicImage(pData, width, height, depth, format, ...) to be compatible
195	with future Ogre versions.
196	*/
197	Image& loadDynamicImage( uchar* pData, size_t uWidth,
198	size_t uHeight, PixelFormat eFormat)
199	{
200	return loadDynamicImage(pData, uWidth, uHeight, 1, eFormat);
201	}
202	/** Loads raw data from a stream. See the function
203	loadDynamicImage for a description of the parameters.
204	@remarks
205	The size of the buffer must be numFaces*PixelUtil::getMemorySize(width, height, depth, format)
206	@note
207	Whilst typically your image is likely to be a simple 2D image,
208	you can define complex images including cube maps
209	and images including custom mip levels. The layout of the
210	internal memory should be:
211	<ul><li>face 0, mip 0 (top), width x height (x depth)</li>
212	<li>face 0, mip 1, width/2 x height/2 (x depth/2)</li>
213	<li>face 0, mip 2, width/4 x height/4 (x depth/4)</li>
214	<li>.. remaining mips for face 0 .. </li>
215	<li>face 1, mip 0 (top), width x height (x depth)</li
216	<li>.. and so on. </li>
217	</ul>
218	Of course, you will never have multiple faces (cube map) and
219	depth too.
220	*/
221	Image & loadRawData(
222	DataStreamPtr& stream,
223	size_t uWidth, size_t uHeight, size_t uDepth,
224	PixelFormat eFormat,
225	size_t numFaces = 1, size_t numMipMaps = 0);
226	/** Loads raw data from a stream. The pixel format has to be specified.
227	@remarks This function is deprecated; one should really use the
228	Image::loadRawData(stream, width, height, depth, format, ...) to be compatible
229	with future Ogre versions.
230	@note
231	Whilst typically your image is likely to be a simple 2D image,
232	you can define complex images including cube maps
233	and images including custom mip levels. The layout of the
234	internal memory should be:
235	<ul><li>face 0, mip 0 (top), width x height</li>
236	<li>face 0, mip 1, width/2 x height/2 </li>
237	<li>face 0, mip 2, width/4 x height/4 </li>
238	<li>.. remaining mips for face 0 .. </li>
239	<li>face 1, mip 0 (top), width x height (x depth)</li
240	<li>.. and so on. </li>
241	</ul>
242	Of course, you will never have multiple faces (cube map) and
243	depth too.
244	*/
245	Image & loadRawData(
246	DataStreamPtr& stream,
247	size_t uWidth, size_t uHeight,
248	PixelFormat eFormat )
249	{
250	return loadRawData(stream, uWidth, uHeight, 1, eFormat);
251	}
252
253	/** Loads an image file.
254	@remarks
255	This method loads an image into memory. Any format for which
256	and associated ImageCodec is registered can be loaded.
257	This can include complex formats like DDS with embedded custom
258	mipmaps, cube faces and volume textures.
259	The type can be determined by calling getFormat().
260	@param
261	strFileName Name of a file file to load.
262	@param
263	groupName Name of the resource group to search for the image
264	@note
265	The memory associated with this buffer is destroyed with the
266	Image object.
267	*/
268	Image & load( const String& strFileName, const String& groupName );
269
270	/** Loads an image file from a stream.
271	@remarks
272	This method works in the same way as the filename-based load
273	method except it loads the image from a DataStream object.
274	This DataStream is expected to contain the
275	encoded data as it would be held in a file.
276	Any format for which and associated ImageCodec is registered
277	can be loaded.
278	This can include complex formats like DDS with embedded custom
279	mipmaps, cube faces and volume textures.
280	The type can be determined by calling getFormat().
281	@param
282	stream The source data.
283	@param
284	type The type of the image. Used to decide what decompression
285	codec to use.
286	@see
287	Image::load( const String& strFileName )
288	*/
289	Image & load(DataStreamPtr& stream, const String& type );
290
291	/** Save the image as a file. */
292	void save(const String& filename);
293
294	/** Returns a pointer to the internal image buffer.
295	@remarks
296	Be careful with this method. You will almost certainly
297	prefer to use getPixelBox, especially with complex images
298	which include many faces or custom mipmaps.
299	*/
300	uchar* getData(void);
301
302	/** Returns a const pointer to the internal image buffer.
303	@remarks
304	Be careful with this method. You will almost certainly
305	prefer to use getPixelBox, especially with complex images
306	which include many faces or custom mipmaps.
307	*/
308	const uchar * getData() const;
309
310	/** Returns the size of the data buffer.
311	*/
312	size_t getSize() const;
313
314	/** Returns the number of mipmaps contained in the image.
315	*/
316	size_t getNumMipmaps() const;
317
318	/** Returns true if the image has the appropriate flag set.
319	*/
320	bool hasFlag(const ImageFlags imgFlag) const;
321
322	/** Gets the width of the image in pixels.
323	*/
324	size_t getWidth(void) const;
325
326	/** Gets the height of the image in pixels.
327	*/
328	size_t getHeight(void) const;
329
330	/** Gets the depth of the image.
331	*/
332	size_t getDepth(void) const;
333
334	/** Get the numer of faces of the image. This is usually 6 for a cubemap, and
335	1 for a normal image.
336	*/
337	size_t getNumFaces(void) const;
338
339	/** Gets the physical width in bytes of each row of pixels.
340	*/
341	size_t getRowSpan(void) const;
342
343	/** Returns the image format.
344	*/
345	PixelFormat getFormat() const;
346
347	/** Returns the number of bits per pixel.
348	*/
349	uchar getBPP() const;
350
351	/** Returns true if the image has an alpha component.
352	*/
353	bool getHasAlpha() const;
354
355	/** Does gamma adjustment.
356	@note
357	Basic algo taken from Titan Engine, copyright (c) 2000 Ignacio
358	Castano Iguado
359	*/
360	static void applyGamma( uchar *buffer, Real gamma, size_t size, uchar bpp );
361
362	/**
363	* Get colour value from a certain location in the image. The z coordinate
364	* is only valid for cubemaps and volume textures. This uses the first (largest)
365	* mipmap.
366	*/
367	ColourValue getColourAt(int x, int y, int z);
368
369	/**
370	* Get a PixelBox encapsulating the image data of a mipmap
371	*/
372	PixelBox getPixelBox(size_t face = 0, size_t mipmap = 0) const;
373
374	enum Filter
375	{
376	FILTER_NEAREST,
377	FILTER_LINEAR,
378	FILTER_BILINEAR,
379	FILTER_BOX,
380	FILTER_TRIANGLE,
381	FILTER_BICUBIC
382	};
383	/** Scale a 1D, 2D or 3D image volume.
384	@param src PixelBox containing the source pointer, dimensions and format
385	@param dst PixelBox containing the destination pointer, dimensions and format
386	@param filter Which filter to use
387	@remarks This function can do pixel format conversion in the process.
388	@note dst and src can point to the same PixelBox object without any problem
389	*/
390	static void scale(const PixelBox &src, const PixelBox &dst, Filter filter = FILTER_BILINEAR);
391
392	/** Resize a 2D image, applying the appropriate filter. */
393	void resize(ushort width, ushort height, Filter filter = FILTER_BILINEAR);
394
395	// Static function to calculate size in bytes from the number of mipmaps, faces and the dimensions
396	static size_t calculateSize(size_t mipmaps, size_t faces, size_t width, size_t height, size_t depth, PixelFormat format);
397	private:
398	// The width of the image in pixels
399	size_t m_uWidth;
400	// The height of the image in pixels
401	size_t m_uHeight;
402	// The depth of the image
403	size_t m_uDepth;
404	// The size of the image buffer
405	size_t m_uSize;
406	// The number of mipmaps the image contains
407	size_t m_uNumMipmaps;
408	// Image specific flags.
409	int m_uFlags;
410
411	// The pixel format of the image
412	PixelFormat m_eFormat;
413
414	// The number of bytes per pixel
415	uchar m_ucPixelSize;
416	uchar* m_pBuffer;
417
418	// A bool to determine if we delete the buffer or the calling app does
419	bool m_bAutoDelete;
420	};
421
422	typedef std::vector<Image*> ImagePtrList;
423	typedef std::vector<const Image*> ConstImagePtrList;
424
425
426	} // namespace
427
428	#endif

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

Context Navigation

source: downloads/ogre/OgreMain/include/OgreImage.h @ 29

Download in other formats: