ITexture Interface
- Load
- IsLoaded
- Unload
- Enable
- IsEnabled
- Blend
- GetBlendFlag
- UseTexture
- LoadFromHandle
ITexture interface manages texture of a surface. There are three ways to
obtain reference to ITexture.
1. Query from the correspondent ISection. In this
case the loaded texture will be applied to all surfaces in the object.
2. Query
from a IElement implemented by a patch strip of the object (IModel->ISection->IStrip->IElement->ITexture).
This method will apply the texture to a patch strip of side surface of the object (not top or
bottom surfaces). After modifications of the texture obtained in this way a call to IItem.SetModified() is required for the changes to take effect. IItem can be quired from the ISection obtained via the above query.
3. Using IPropertyArray of the object. ( IModel->ISection->IPropertyArray->IArray
("TextureArray") ->ITexture
). In the last method the texture array has the back surface texture as its
element 0 and front texture as its element 1. Element 2 in the array will be the
texture of side surface 0, Element 3 in the array will be the
texture of side surface 1, etc.
UseTexture method of the interface
allows sharing of a texture among different patch strips or surfaces.
See also Textures and Texture Programming
sample.
HRESULT Load(char *szFilePath)
Parameters
szFilePath- [in] full path of a .bmp
(bitmap) file
Returns
- S_OK in case of
success.
DISP_E_PARAMNOTOPTIONAL - in case szFilePath is
not a valid path or file can not be opened for reading.
Remarks:
This method loads the image into memory and assigns the texture to the
surface(s) (see above). To be displayed the texture has to be activated using an
Enable() method.
HRESULT IsLoaded(VARIANT_BOOL *pbLoaded)
Parameters
pbLoaded - [out] pointer to a Boolean variable,
which will be set to true if the texture is loaded and false otherwise.
Return Values
- S_OK in case of success.
- Remarks::
-
- Use this method to check at runtime if a surface has a texture assigned to
it.
HRESULT Unload()
Returns
- S_OK
Remarks:
This method removes reference to the texture from the surface. If there is no
other surfaces using the texture frees all resources allocated for the
texture.
HRESULT Enable(VARIANT_BOOL bEnable)
Parameters
bEnable - [in] new value of the
enabled state.
Returns
- S_OK in case of
success.
DISP_E_PARAMNOTOPTIONAL - if the texture is not loaded.
Remarks:
Activates or deactivates texture which is loaded for the surface. When
enabled the texture will be rendered in 3D View.
HRESULT IsEnabled(VARIANT_BOOL *pbEnabled)
Parameters
pbEnabled - [out] pointer to a Boolean variable,
which will be set to true if the texture is enabled and false otherwise.
Returns
- S_OK in case of
success.
DISP_E_PARAMNOTOPTIONAL - if the texture is not loaded.
Remarks:
This method retrieves current state of enabled flag.
HRESULT Blend(VARIANT_BOOL bBlend)
Parameters
bBlend - [in] if true the texture
will be rendered combined with underlying color of the surface material and
lighting.
Returns
- S_OK in case of
success.
DISP_E_PARAMNOTOPTIONAL - if the texture is not loaded.
Remarks:
By default the texture is applied to the surface by blending with
underlying color of the surface material. Lighting is also used to render the
surface. If this property is disabled by using Blend() method the surface
will be rendered by using the texture only.
HRESULT GetBlendFlag(VARIANT_BOOL *pbBlend)
Parameters
pbBlend - [out] pointer to a Boolean variable,
which will be set to true if blending is enabled.
Returns
- S_OK in case of
success.
DISP_E_PARAMNOTOPTIONAL - if the texture is not loaded.
Remarks:
This method retrieves current state of blend flag (See comments for
Blend() method).
HRESULT UseTexture(ITexture* pITexture)
Parameters
pITexture - [in] Reference to
ITexture interface implemented by another surface which will be sharing the
texture.
Returns
- S_OK in case of
success.
DISP_E_PARAMNOTOPTIONAL - if the texture is not loaded.
Remarks:
To save resources and improve performance surfaces can re-use textures. After
call to this method the current surface will be sharing the texture with the
surface, which loaded pITexture.
HRESULT LoadFromHandle(int handle)
Parameters
handle - [in]
HBITMAP handle of a bitmap loaded into memory reinterpreted as 32 bits signed
integer type
Returns
- S_OK in case of
success.
DISP_E_PARAMNOTOPTIONAL - if the texture could not be copied. The most
frequent reason for this is that the handle is not a valid handle of a loaded
bitmap.
Remarks:
The method copies data from a bitmap loaded in memory. The actual type of the
handle parameter must be HBITMAP. (See LoadBitmap() API
in C++ documentation for your development Environment for more details). This
method is mostly suppled for usage by native environments. After call to this
method the memory used by the bitmap can be freed independently of the texture.
|