Line data Source code
1 : // Copyright (C) 2002-2012 Nikolaus Gebhardt
2 : // This file is part of the "Irrlicht Engine".
3 : // For conditions of distribution and use, see copyright notice in irrlicht.h
4 :
5 : #ifndef __I_TEXTURE_H_INCLUDED__
6 : #define __I_TEXTURE_H_INCLUDED__
7 :
8 : #include "IReferenceCounted.h"
9 : #include "IImage.h"
10 : #include "dimension2d.h"
11 : #include "EDriverTypes.h"
12 : #include "path.h"
13 : #include "matrix4.h"
14 :
15 : namespace irr
16 : {
17 : namespace video
18 : {
19 :
20 :
21 : //! Enumeration flags telling the video driver in which format textures should be created.
22 : enum E_TEXTURE_CREATION_FLAG
23 : {
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
28 : the space in memory.
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,
33 :
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,
42 :
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
48 : the same time. */
49 : ETCF_OPTIMIZED_FOR_QUALITY = 0x00000004,
50 :
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,
55 : at the same time. */
56 : ETCF_OPTIMIZED_FOR_SPEED = 0x00000008,
57 :
58 : /** Automatically creates mip map levels for the textures. */
59 : ETCF_CREATE_MIP_MAPS = 0x00000010,
60 :
61 : /** Discard any alpha layer and use non-alpha color format. */
62 : ETCF_NO_ALPHA_CHANNEL = 0x00000020,
63 :
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,
67 :
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
71 : };
72 :
73 : //! Enum for the mode for texture locking. Read-Only, write-only or read/write.
74 : enum E_TEXTURE_LOCK_MODE
75 : {
76 : //! The default mode. Texture can be read and written to.
77 : ETLM_READ_WRITE = 0,
78 :
79 : //! Read only. The texture is downloaded, but not uploaded again.
80 : /** Often used to read back shader generated textures. */
81 : ETLM_READ_ONLY,
82 :
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. */
86 : ETLM_WRITE_ONLY
87 : };
88 :
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.
97 : */
98 : class ITexture : public virtual IReferenceCounted
99 : {
100 : public:
101 :
102 : //! constructor
103 : ITexture(const io::path& name) : NamedPath(name)
104 : {
105 : }
106 :
107 : //! Lock function.
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
114 : unlocked.
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;
128 :
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;
133 :
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;
143 :
144 : //! Get dimension (=size) of the texture.
145 : /** \return The size of the texture. */
146 : virtual const core::dimension2d<u32>& getSize() const = 0;
147 :
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;
154 :
155 : //! Get the color format of texture.
156 : /** \return The color format of texture. */
157 : virtual ECOLOR_FORMAT getColorFormat() const = 0;
158 :
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
161 : texture.
162 : \return Pitch of texture in bytes. */
163 : virtual u32 getPitch() const = 0;
164 :
165 : //! Check whether the texture has MipMaps
166 : /** \return True if texture has MipMaps, else false. */
167 : virtual bool hasMipMaps() const { return false; }
168 :
169 : //! Returns if the texture has an alpha channel
170 : virtual bool hasAlpha() const {
171 : return getColorFormat () == video::ECF_A8R8G8B8 || getColorFormat () == video::ECF_A1R5G5B5;
172 : }
173 :
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;
182 :
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; }
189 :
190 : //! Get name of texture (in most cases this is the filename)
191 3 : const io::SNamedPath& getName() const { return NamedPath; }
192 :
193 : protected:
194 :
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)
199 : {
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;
209 : }
210 :
211 : io::SNamedPath NamedPath;
212 : };
213 :
214 :
215 : } // end namespace video
216 : } // end namespace irr
217 :
218 : #endif
219 :
|
