1
// Copyright (C) 2002-2011 Nikolaus Gebhardt
2
// This file is part of the "Irrlicht Engine".
3
// For conditions of distribution and use, see copyright notice in irrlicht.h
5
#ifndef __I_TEXTURE_H_INCLUDED__
6
#define __I_TEXTURE_H_INCLUDED__
8
#include "IReferenceCounted.h"
10
#include "dimension2d.h"
11
#include "EDriverTypes.h"
21
//! Enumeration flags telling the video driver in which format textures should be created.
22
enum E_TEXTURE_CREATION_FLAG
24
/** Forces the driver to create 16 bit textures always, independent of
25
which format the file on disk has. When choosing this you may lose
26
some color detail, but gain much speed and memory. 16 bit textures can
27
be transferred twice as fast as 32 bit textures and only use half of
29
When using this flag, it does not make sense to use the flags
30
ETCF_ALWAYS_32_BIT, ETCF_OPTIMIZED_FOR_QUALITY, or
31
ETCF_OPTIMIZED_FOR_SPEED at the same time. */
32
ETCF_ALWAYS_16_BIT = 0x00000001,
34
/** Forces the driver to create 32 bit textures always, independent of
35
which format the file on disk has. Please note that some drivers (like
36
the software device) will ignore this, because they are only able to
37
create and use 16 bit textures.
38
When using this flag, it does not make sense to use the flags
39
ETCF_ALWAYS_16_BIT, ETCF_OPTIMIZED_FOR_QUALITY, or
40
ETCF_OPTIMIZED_FOR_SPEED at the same time. */
41
ETCF_ALWAYS_32_BIT = 0x00000002,
43
/** Lets the driver decide in which format the textures are created and
44
tries to make the textures look as good as possible. Usually it simply
45
chooses the format in which the texture was stored on disk.
46
When using this flag, it does not make sense to use the flags
47
ETCF_ALWAYS_16_BIT, ETCF_ALWAYS_32_BIT, or ETCF_OPTIMIZED_FOR_SPEED at
49
ETCF_OPTIMIZED_FOR_QUALITY = 0x00000004,
51
/** Lets the driver decide in which format the textures are created and
52
tries to create them maximizing render speed.
53
When using this flag, it does not make sense to use the flags
54
ETCF_ALWAYS_16_BIT, ETCF_ALWAYS_32_BIT, or ETCF_OPTIMIZED_FOR_QUALITY,
56
ETCF_OPTIMIZED_FOR_SPEED = 0x00000008,
58
/** Automatically creates mip map levels for the textures. */
59
ETCF_CREATE_MIP_MAPS = 0x00000010,
61
/** Discard any alpha layer and use non-alpha color format. */
62
ETCF_NO_ALPHA_CHANNEL = 0x00000020,
64
//! Allow the Driver to use Non-Power-2-Textures
65
/** BurningVideo can handle Non-Power-2 Textures in 2D (GUI), but not in 3D. */
66
ETCF_ALLOW_NON_POWER_2 = 0x00000040,
68
/** This flag is never used, it only forces the compiler to compile
69
these enumeration values to 32 bit. */
70
ETCF_FORCE_32_BIT_DO_NOT_USE = 0x7fffffff
73
//! Enum for the mode for texture locking. Read-Only, write-only or read/write.
74
enum E_TEXTURE_LOCK_MODE
76
//! The default mode. Texture can be read and written to.
79
//! Read only. The texture is downloaded, but not uploaded again.
80
/** Often used to read back shader generated textures. */
83
//! Write only. The texture is not downloaded and might be uninitialised.
84
/** The updated texture is uploaded to the GPU.
85
Used for initialising the shader from the CPU. */
89
//! Interface of a Video Driver dependent Texture.
90
/** An ITexture is created by an IVideoDriver by using IVideoDriver::addTexture
91
or IVideoDriver::getTexture. After that, the texture may only be used by this
92
VideoDriver. As you can imagine, textures of the DirectX and the OpenGL device
93
will, e.g., not be compatible. An exception is the Software device and the
94
NULL device, their textures are compatible. If you try to use a texture
95
created by one device with an other device, the device will refuse to do that
96
and write a warning or an error message to the output buffer.
98
class ITexture : public virtual IReferenceCounted
103
ITexture(const io::path& name) : NamedPath(name)
108
/** Locks the Texture and returns a pointer to access the
109
pixels. After lock() has been called and all operations on the pixels
110
are done, you must call unlock().
111
Locks are not accumulating, hence one unlock will do for an arbitrary
112
number of previous locks. You should avoid locking different levels without
113
unlocking inbetween, though, because only the last level locked will be
115
The size of the i-th mipmap level is defined as max(getSize().Width>>i,1)
116
and max(getSize().Height>>i,1)
117
\param mode Specifies what kind of changes to the locked texture are
118
allowed. Unspecified behavior will arise if texture is written in read
119
only mode or read from in write only mode.
120
Support for this feature depends on the driver, so don't rely on the
121
texture being write-protected when locking with read-only, etc.
122
\param mipmapLevel Number of the mipmapLevel to lock. 0 is main texture.
123
Non-existing levels will silently fail and return 0.
124
\return Returns a pointer to the pixel data. The format of the pixel can
125
be determined by using getColorFormat(). 0 is returned, if
126
the texture cannot be locked. */
127
virtual void* lock(E_TEXTURE_LOCK_MODE mode=ETLM_READ_WRITE, u32 mipmapLevel=0) = 0;
129
//! Unlock function. Must be called after a lock() to the texture.
130
/** One should avoid to call unlock more than once before another lock.
131
The last locked mip level will be unlocked. */
132
virtual void unlock() = 0;
134
//! Get original size of the texture.
135
/** The texture is usually scaled, if it was created with an unoptimal
136
size. For example if the size was not a power of two. This method
137
returns the size of the texture it had before it was scaled. Can be
138
useful when drawing 2d images on the screen, which should have the
139
exact size of the original texture. Use ITexture::getSize() if you want
140
to know the real size it has now stored in the system.
141
\return The original size of the texture. */
142
virtual const core::dimension2d<u32>& getOriginalSize() const = 0;
144
//! Get dimension (=size) of the texture.
145
/** \return The size of the texture. */
146
virtual const core::dimension2d<u32>& getSize() const = 0;
148
//! Get driver type of texture.
149
/** This is the driver, which created the texture. This method is used
150
internally by the video devices, to check, if they may use a texture
151
because textures may be incompatible between different devices.
152
\return Driver type of texture. */
153
virtual E_DRIVER_TYPE getDriverType() const = 0;
155
//! Get the color format of texture.
156
/** \return The color format of texture. */
157
virtual ECOLOR_FORMAT getColorFormat() const = 0;
159
//! Get pitch of the main texture (in bytes).
160
/** The pitch is the amount of bytes used for a row of pixels in a
162
\return Pitch of texture in bytes. */
163
virtual u32 getPitch() const = 0;
165
//! Check whether the texture has MipMaps
166
/** \return True if texture has MipMaps, else false. */
167
virtual bool hasMipMaps() const { return false; }
169
//! Returns if the texture has an alpha channel
170
virtual bool hasAlpha() const {
171
return getColorFormat () == video::ECF_A8R8G8B8 || getColorFormat () == video::ECF_A1R5G5B5;
174
//! Regenerates the mip map levels of the texture.
175
/** Required after modifying the texture, usually after calling unlock().
176
\param mipmapData Optional parameter to pass in image data which will be
177
used instead of the previously stored or automatically generated mipmap
178
data. The data has to be a continuous pixel data for all mipmaps until
179
1x1 pixel. Each mipmap has to be half the width and height of the previous
180
level. At least one pixel will be always kept.*/
181
virtual void regenerateMipMapLevels(void* mipmapData=0) = 0;
183
//! Check whether the texture is a render target
184
/** Render targets can be set as such in the video driver, in order to
185
render a scene into the texture. Once unbound as render target, they can
186
be used just as usual textures again.
187
\return True if this is a render target, otherwise false. */
188
virtual bool isRenderTarget() const { return false; }
190
//! Get name of texture (in most cases this is the filename)
191
const io::SNamedPath& getName() const { return NamedPath; }
195
//! Helper function, helps to get the desired texture creation format from the flags.
196
/** \return Either ETCF_ALWAYS_32_BIT, ETCF_ALWAYS_16_BIT,
197
ETCF_OPTIMIZED_FOR_QUALITY, or ETCF_OPTIMIZED_FOR_SPEED. */
198
inline E_TEXTURE_CREATION_FLAG getTextureFormatFromFlags(u32 flags)
200
if (flags & ETCF_OPTIMIZED_FOR_SPEED)
201
return ETCF_OPTIMIZED_FOR_SPEED;
202
if (flags & ETCF_ALWAYS_16_BIT)
203
return ETCF_ALWAYS_16_BIT;
204
if (flags & ETCF_ALWAYS_32_BIT)
205
return ETCF_ALWAYS_32_BIT;
206
if (flags & ETCF_OPTIMIZED_FOR_QUALITY)
207
return ETCF_OPTIMIZED_FOR_QUALITY;
208
return ETCF_OPTIMIZED_FOR_SPEED;
211
io::SNamedPath NamedPath;
215
} // end namespace video
216
} // end namespace irr
added
removed
include/ITexture.h
