miniassimp
view include/miniassimp/material.h @ 0:879c81d94345
initial commit
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Mon, 28 Jan 2019 18:19:26 +0200 |
| parents | |
| children |
line source
1 /*
2 ---------------------------------------------------------------------------
3 Open Asset Import Library (assimp)
4 ---------------------------------------------------------------------------
6 Copyright (c) 2006-2018, assimp team
10 All rights reserved.
12 Redistribution and use of this software in source and binary forms,
13 with or without modification, are permitted provided that the following
14 conditions are met:
16 * Redistributions of source code must retain the above
17 copyright notice, this list of conditions and the
18 following disclaimer.
20 * Redistributions in binary form must reproduce the above
21 copyright notice, this list of conditions and the
22 following disclaimer in the documentation and/or other
23 materials provided with the distribution.
25 * Neither the name of the assimp team, nor the names of its
26 contributors may be used to endorse or promote products
27 derived from this software without specific prior
28 written permission of the assimp team.
30 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
31 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
32 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
33 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
34 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
35 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
36 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
37 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
38 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
39 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
40 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
41 ---------------------------------------------------------------------------
42 */
44 /** @file material.h
45 * @brief Defines the material system of the library
46 */
47 #pragma once
48 #ifndef AI_MATERIAL_H_INC
49 #define AI_MATERIAL_H_INC
51 #include "types.h"
53 #ifdef __cplusplus
54 extern "C" {
55 #endif
57 // Name for default materials (2nd is used if meshes have UV coords)
58 #define AI_DEFAULT_MATERIAL_NAME "DefaultMaterial"
60 // ---------------------------------------------------------------------------
61 /** @brief Defines how the Nth texture of a specific type is combined with
62 * the result of all previous layers.
63 *
64 * Example (left: key, right: value): <br>
65 * @code
66 * DiffColor0 - gray
67 * DiffTextureOp0 - aiTextureOpMultiply
68 * DiffTexture0 - tex1.png
69 * DiffTextureOp0 - aiTextureOpAdd
70 * DiffTexture1 - tex2.png
71 * @endcode
72 * Written as equation, the final diffuse term for a specific pixel would be:
73 * @code
74 * diffFinal = DiffColor0 * sampleTex(DiffTexture0,UV0) +
75 * sampleTex(DiffTexture1,UV0) * diffContrib;
76 * @endcode
77 * where 'diffContrib' is the intensity of the incoming light for that pixel.
78 */
79 enum aiTextureOp
80 {
81 /** T = T1 * T2 */
82 aiTextureOp_Multiply = 0x0,
84 /** T = T1 + T2 */
85 aiTextureOp_Add = 0x1,
87 /** T = T1 - T2 */
88 aiTextureOp_Subtract = 0x2,
90 /** T = T1 / T2 */
91 aiTextureOp_Divide = 0x3,
93 /** T = (T1 + T2) - (T1 * T2) */
94 aiTextureOp_SmoothAdd = 0x4,
96 /** T = T1 + (T2-0.5) */
97 aiTextureOp_SignedAdd = 0x5,
100 #ifndef SWIG
101 _aiTextureOp_Force32Bit = INT_MAX
102 #endif
103 };
105 // ---------------------------------------------------------------------------
106 /** @brief Defines how UV coordinates outside the [0...1] range are handled.
107 *
108 * Commonly referred to as 'wrapping mode'.
109 */
110 enum aiTextureMapMode
111 {
112 /** A texture coordinate u|v is translated to u%1|v%1
113 */
114 aiTextureMapMode_Wrap = 0x0,
116 /** Texture coordinates outside [0...1]
117 * are clamped to the nearest valid value.
118 */
119 aiTextureMapMode_Clamp = 0x1,
121 /** If the texture coordinates for a pixel are outside [0...1]
122 * the texture is not applied to that pixel
123 */
124 aiTextureMapMode_Decal = 0x3,
126 /** A texture coordinate u|v becomes u%1|v%1 if (u-(u%1))%2 is zero and
127 * 1-(u%1)|1-(v%1) otherwise
128 */
129 aiTextureMapMode_Mirror = 0x2,
131 #ifndef SWIG
132 _aiTextureMapMode_Force32Bit = INT_MAX
133 #endif
134 };
136 // ---------------------------------------------------------------------------
137 /** @brief Defines how the mapping coords for a texture are generated.
138 *
139 * Real-time applications typically require full UV coordinates, so the use of
140 * the aiProcess_GenUVCoords step is highly recommended. It generates proper
141 * UV channels for non-UV mapped objects, as long as an accurate description
142 * how the mapping should look like (e.g spherical) is given.
143 * See the #AI_MATKEY_MAPPING property for more details.
144 */
145 enum aiTextureMapping
146 {
147 /** The mapping coordinates are taken from an UV channel.
148 *
149 * The #AI_MATKEY_UVWSRC key specifies from which UV channel
150 * the texture coordinates are to be taken from (remember,
151 * meshes can have more than one UV channel).
152 */
153 aiTextureMapping_UV = 0x0,
155 /** Spherical mapping */
156 aiTextureMapping_SPHERE = 0x1,
158 /** Cylindrical mapping */
159 aiTextureMapping_CYLINDER = 0x2,
161 /** Cubic mapping */
162 aiTextureMapping_BOX = 0x3,
164 /** Planar mapping */
165 aiTextureMapping_PLANE = 0x4,
167 /** Undefined mapping. Have fun. */
168 aiTextureMapping_OTHER = 0x5,
171 #ifndef SWIG
172 _aiTextureMapping_Force32Bit = INT_MAX
173 #endif
174 };
176 // ---------------------------------------------------------------------------
177 /** @brief Defines the purpose of a texture
178 *
179 * This is a very difficult topic. Different 3D packages support different
180 * kinds of textures. For very common texture types, such as bumpmaps, the
181 * rendering results depend on implementation details in the rendering
182 * pipelines of these applications. Assimp loads all texture references from
183 * the model file and tries to determine which of the predefined texture
184 * types below is the best choice to match the original use of the texture
185 * as closely as possible.<br>
186 *
187 * In content pipelines you'll usually define how textures have to be handled,
188 * and the artists working on models have to conform to this specification,
189 * regardless which 3D tool they're using.
190 */
191 enum aiTextureType
192 {
193 /** Dummy value.
194 *
195 * No texture, but the value to be used as 'texture semantic'
196 * (#aiMaterialProperty::mSemantic) for all material properties
197 * *not* related to textures.
198 */
199 aiTextureType_NONE = 0x0,
203 /** The texture is combined with the result of the diffuse
204 * lighting equation.
205 */
206 aiTextureType_DIFFUSE = 0x1,
208 /** The texture is combined with the result of the specular
209 * lighting equation.
210 */
211 aiTextureType_SPECULAR = 0x2,
213 /** The texture is combined with the result of the ambient
214 * lighting equation.
215 */
216 aiTextureType_AMBIENT = 0x3,
218 /** The texture is added to the result of the lighting
219 * calculation. It isn't influenced by incoming light.
220 */
221 aiTextureType_EMISSIVE = 0x4,
223 /** The texture is a height map.
224 *
225 * By convention, higher gray-scale values stand for
226 * higher elevations from the base height.
227 */
228 aiTextureType_HEIGHT = 0x5,
230 /** The texture is a (tangent space) normal-map.
231 *
232 * Again, there are several conventions for tangent-space
233 * normal maps. Assimp does (intentionally) not
234 * distinguish here.
235 */
236 aiTextureType_NORMALS = 0x6,
238 /** The texture defines the glossiness of the material.
239 *
240 * The glossiness is in fact the exponent of the specular
241 * (phong) lighting equation. Usually there is a conversion
242 * function defined to map the linear color values in the
243 * texture to a suitable exponent. Have fun.
244 */
245 aiTextureType_SHININESS = 0x7,
247 /** The texture defines per-pixel opacity.
248 *
249 * Usually 'white' means opaque and 'black' means
250 * 'transparency'. Or quite the opposite. Have fun.
251 */
252 aiTextureType_OPACITY = 0x8,
254 /** Displacement texture
255 *
256 * The exact purpose and format is application-dependent.
257 * Higher color values stand for higher vertex displacements.
258 */
259 aiTextureType_DISPLACEMENT = 0x9,
261 /** Lightmap texture (aka Ambient Occlusion)
262 *
263 * Both 'Lightmaps' and dedicated 'ambient occlusion maps' are
264 * covered by this material property. The texture contains a
265 * scaling value for the final color value of a pixel. Its
266 * intensity is not affected by incoming light.
267 */
268 aiTextureType_LIGHTMAP = 0xA,
270 /** Reflection texture
271 *
272 * Contains the color of a perfect mirror reflection.
273 * Rarely used, almost never for real-time applications.
274 */
275 aiTextureType_REFLECTION = 0xB,
277 /** Unknown texture
278 *
279 * A texture reference that does not match any of the definitions
280 * above is considered to be 'unknown'. It is still imported,
281 * but is excluded from any further postprocessing.
282 */
283 aiTextureType_UNKNOWN = 0xC,
286 #ifndef SWIG
287 _aiTextureType_Force32Bit = INT_MAX
288 #endif
289 };
291 #define AI_TEXTURE_TYPE_MAX aiTextureType_UNKNOWN
293 // ---------------------------------------------------------------------------
294 /** @brief Defines all shading models supported by the library
295 *
296 * The list of shading modes has been taken from Blender.
297 * See Blender documentation for more information. The API does
298 * not distinguish between "specular" and "diffuse" shaders (thus the
299 * specular term for diffuse shading models like Oren-Nayar remains
300 * undefined). <br>
301 * Again, this value is just a hint. Assimp tries to select the shader whose
302 * most common implementation matches the original rendering results of the
303 * 3D modeller which wrote a particular model as closely as possible.
304 */
305 enum aiShadingMode
306 {
307 /** Flat shading. Shading is done on per-face base,
308 * diffuse only. Also known as 'faceted shading'.
309 */
310 aiShadingMode_Flat = 0x1,
312 /** Simple Gouraud shading.
313 */
314 aiShadingMode_Gouraud = 0x2,
316 /** Phong-Shading -
317 */
318 aiShadingMode_Phong = 0x3,
320 /** Phong-Blinn-Shading
321 */
322 aiShadingMode_Blinn = 0x4,
324 /** Toon-Shading per pixel
325 *
326 * Also known as 'comic' shader.
327 */
328 aiShadingMode_Toon = 0x5,
330 /** OrenNayar-Shading per pixel
331 *
332 * Extension to standard Lambertian shading, taking the
333 * roughness of the material into account
334 */
335 aiShadingMode_OrenNayar = 0x6,
337 /** Minnaert-Shading per pixel
338 *
339 * Extension to standard Lambertian shading, taking the
340 * "darkness" of the material into account
341 */
342 aiShadingMode_Minnaert = 0x7,
344 /** CookTorrance-Shading per pixel
345 *
346 * Special shader for metallic surfaces.
347 */
348 aiShadingMode_CookTorrance = 0x8,
350 /** No shading at all. Constant light influence of 1.0.
351 */
352 aiShadingMode_NoShading = 0x9,
354 /** Fresnel shading
355 */
356 aiShadingMode_Fresnel = 0xa,
359 #ifndef SWIG
360 _aiShadingMode_Force32Bit = INT_MAX
361 #endif
362 };
365 // ---------------------------------------------------------------------------
366 /** @brief Defines some mixed flags for a particular texture.
367 *
368 * Usually you'll instruct your cg artists how textures have to look like ...
369 * and how they will be processed in your application. However, if you use
370 * Assimp for completely generic loading purposes you might also need to
371 * process these flags in order to display as many 'unknown' 3D models as
372 * possible correctly.
373 *
374 * This corresponds to the #AI_MATKEY_TEXFLAGS property.
375 */
376 enum aiTextureFlags
377 {
378 /** The texture's color values have to be inverted (componentwise 1-n)
379 */
380 aiTextureFlags_Invert = 0x1,
382 /** Explicit request to the application to process the alpha channel
383 * of the texture.
384 *
385 * Mutually exclusive with #aiTextureFlags_IgnoreAlpha. These
386 * flags are set if the library can say for sure that the alpha
387 * channel is used/is not used. If the model format does not
388 * define this, it is left to the application to decide whether
389 * the texture alpha channel - if any - is evaluated or not.
390 */
391 aiTextureFlags_UseAlpha = 0x2,
393 /** Explicit request to the application to ignore the alpha channel
394 * of the texture.
395 *
396 * Mutually exclusive with #aiTextureFlags_UseAlpha.
397 */
398 aiTextureFlags_IgnoreAlpha = 0x4,
400 #ifndef SWIG
401 _aiTextureFlags_Force32Bit = INT_MAX
402 #endif
403 };
406 // ---------------------------------------------------------------------------
407 /** @brief Defines alpha-blend flags.
408 *
409 * If you're familiar with OpenGL or D3D, these flags aren't new to you.
410 * They define *how* the final color value of a pixel is computed, basing
411 * on the previous color at that pixel and the new color value from the
412 * material.
413 * The blend formula is:
414 * @code
415 * SourceColor * SourceBlend + DestColor * DestBlend
416 * @endcode
417 * where DestColor is the previous color in the framebuffer at this
418 * position and SourceColor is the material color before the transparency
419 * calculation.<br>
420 * This corresponds to the #AI_MATKEY_BLEND_FUNC property.
421 */
422 enum aiBlendMode
423 {
424 /**
425 * Formula:
426 * @code
427 * SourceColor*SourceAlpha + DestColor*(1-SourceAlpha)
428 * @endcode
429 */
430 aiBlendMode_Default = 0x0,
432 /** Additive blending
433 *
434 * Formula:
435 * @code
436 * SourceColor*1 + DestColor*1
437 * @endcode
438 */
439 aiBlendMode_Additive = 0x1,
441 // we don't need more for the moment, but we might need them
442 // in future versions ...
444 #ifndef SWIG
445 _aiBlendMode_Force32Bit = INT_MAX
446 #endif
447 };
450 #include "./Compiler/pushpack1.h"
452 // ---------------------------------------------------------------------------
453 /** @brief Defines how an UV channel is transformed.
454 *
455 * This is just a helper structure for the #AI_MATKEY_UVTRANSFORM key.
456 * See its documentation for more details.
457 *
458 * Typically you'll want to build a matrix of this information. However,
459 * we keep separate scaling/translation/rotation values to make it
460 * easier to process and optimize UV transformations internally.
461 */
462 struct aiUVTransform
463 {
464 /** Translation on the u and v axes.
465 *
466 * The default value is (0|0).
467 */
468 C_STRUCT aiVector2D mTranslation;
470 /** Scaling on the u and v axes.
471 *
472 * The default value is (1|1).
473 */
474 C_STRUCT aiVector2D mScaling;
476 /** Rotation - in counter-clockwise direction.
477 *
478 * The rotation angle is specified in radians. The
479 * rotation center is 0.5f|0.5f. The default value
480 * 0.f.
481 */
482 ai_real mRotation;
485 #ifdef __cplusplus
486 aiUVTransform() AI_NO_EXCEPT
487 : mTranslation (0.0,0.0)
488 , mScaling (1.0,1.0)
489 , mRotation (0.0)
490 {
491 // nothing to be done here ...
492 }
493 #endif
495 };
497 #include "./Compiler/poppack1.h"
499 //! @cond AI_DOX_INCLUDE_INTERNAL
500 // ---------------------------------------------------------------------------
501 /** @brief A very primitive RTTI system for the contents of material
502 * properties.
503 */
504 enum aiPropertyTypeInfo
505 {
506 /** Array of single-precision (32 Bit) floats
507 *
508 * It is possible to use aiGetMaterialInteger[Array]() (or the C++-API
509 * aiMaterial::Get()) to query properties stored in floating-point format.
510 * The material system performs the type conversion automatically.
511 */
512 aiPTI_Float = 0x1,
514 /** Array of double-precision (64 Bit) floats
515 *
516 * It is possible to use aiGetMaterialInteger[Array]() (or the C++-API
517 * aiMaterial::Get()) to query properties stored in floating-point format.
518 * The material system performs the type conversion automatically.
519 */
520 aiPTI_Double = 0x2,
522 /** The material property is an aiString.
523 *
524 * Arrays of strings aren't possible, aiGetMaterialString() (or the
525 * C++-API aiMaterial::Get()) *must* be used to query a string property.
526 */
527 aiPTI_String = 0x3,
529 /** Array of (32 Bit) integers
530 *
531 * It is possible to use aiGetMaterialFloat[Array]() (or the C++-API
532 * aiMaterial::Get()) to query properties stored in integer format.
533 * The material system performs the type conversion automatically.
534 */
535 aiPTI_Integer = 0x4,
538 /** Simple binary buffer, content undefined. Not convertible to anything.
539 */
540 aiPTI_Buffer = 0x5,
543 /** This value is not used. It is just there to force the
544 * compiler to map this enum to a 32 Bit integer.
545 */
546 #ifndef SWIG
547 _aiPTI_Force32Bit = INT_MAX
548 #endif
549 };
551 // ---------------------------------------------------------------------------
552 /** @brief Data structure for a single material property
553 *
554 * As an user, you'll probably never need to deal with this data structure.
555 * Just use the provided aiGetMaterialXXX() or aiMaterial::Get() family
556 * of functions to query material properties easily. Processing them
557 * manually is faster, but it is not the recommended way. It isn't worth
558 * the effort. <br>
559 * Material property names follow a simple scheme:
560 * @code
561 * $<name>
562 * ?<name>
563 * A public property, there must be corresponding AI_MATKEY_XXX define
564 * 2nd: Public, but ignored by the #aiProcess_RemoveRedundantMaterials
565 * post-processing step.
566 * ~<name>
567 * A temporary property for internal use.
568 * @endcode
569 * @see aiMaterial
570 */
571 struct aiMaterialProperty
572 {
573 /** Specifies the name of the property (key)
574 * Keys are generally case insensitive.
575 */
576 C_STRUCT aiString mKey;
578 /** Textures: Specifies their exact usage semantic.
579 * For non-texture properties, this member is always 0
580 * (or, better-said, #aiTextureType_NONE).
581 */
582 unsigned int mSemantic;
584 /** Textures: Specifies the index of the texture.
585 * For non-texture properties, this member is always 0.
586 */
587 unsigned int mIndex;
589 /** Size of the buffer mData is pointing to, in bytes.
590 * This value may not be 0.
591 */
592 unsigned int mDataLength;
594 /** Type information for the property.
595 *
596 * Defines the data layout inside the data buffer. This is used
597 * by the library internally to perform debug checks and to
598 * utilize proper type conversions.
599 * (It's probably a hacky solution, but it works.)
600 */
601 C_ENUM aiPropertyTypeInfo mType;
603 /** Binary buffer to hold the property's value.
604 * The size of the buffer is always mDataLength.
605 */
606 char* mData;
608 #ifdef __cplusplus
610 aiMaterialProperty() AI_NO_EXCEPT
611 : mSemantic( 0 )
612 , mIndex( 0 )
613 , mDataLength( 0 )
614 , mType( aiPTI_Float )
615 , mData(0) {
616 // empty
617 }
619 ~aiMaterialProperty() {
620 delete[] mData;
621 mData = 0;
622 }
624 #endif
625 };
626 //! @endcond
628 #ifdef __cplusplus
629 } // We need to leave the "C" block here to allow template member functions
630 #endif
632 // ---------------------------------------------------------------------------
633 /** @brief Data structure for a material
634 *
635 * Material data is stored using a key-value structure. A single key-value
636 * pair is called a 'material property'. C++ users should use the provided
637 * member functions of aiMaterial to process material properties, C users
638 * have to stick with the aiMaterialGetXXX family of unbound functions.
639 * The library defines a set of standard keys (AI_MATKEY_XXX).
640 */
641 #ifdef __cplusplus
642 struct ASSIMP_API aiMaterial
643 #else
644 struct aiMaterial
645 #endif
646 {
648 #ifdef __cplusplus
650 public:
652 aiMaterial();
653 ~aiMaterial();
655 // -------------------------------------------------------------------
656 /**
657 * @brief Returns the name of the material.
658 * @return The name of the material.
659 */
660 // -------------------------------------------------------------------
661 aiString GetName();
663 // -------------------------------------------------------------------
664 /** @brief Retrieve an array of Type values with a specific key
665 * from the material
666 *
667 * @param pKey Key to search for. One of the AI_MATKEY_XXX constants.
668 * @param type .. set by AI_MATKEY_XXX
669 * @param idx .. set by AI_MATKEY_XXX
670 * @param pOut Pointer to a buffer to receive the result.
671 * @param pMax Specifies the size of the given buffer, in Type's.
672 * Receives the number of values (not bytes!) read.
673 * NULL is a valid value for this parameter.
674 */
675 template <typename Type>
676 aiReturn Get(const char* pKey,unsigned int type,
677 unsigned int idx, Type* pOut, unsigned int* pMax) const;
679 aiReturn Get(const char* pKey,unsigned int type,
680 unsigned int idx, int* pOut, unsigned int* pMax) const;
682 aiReturn Get(const char* pKey,unsigned int type,
683 unsigned int idx, ai_real* pOut, unsigned int* pMax) const;
685 // -------------------------------------------------------------------
686 /** @brief Retrieve a Type value with a specific key
687 * from the material
688 *
689 * @param pKey Key to search for. One of the AI_MATKEY_XXX constants.
690 * @param type Specifies the type of the texture to be retrieved (
691 * e.g. diffuse, specular, height map ...)
692 * @param idx Index of the texture to be retrieved.
693 * @param pOut Reference to receive the output value
694 */
695 template <typename Type>
696 aiReturn Get(const char* pKey,unsigned int type,
697 unsigned int idx,Type& pOut) const;
700 aiReturn Get(const char* pKey,unsigned int type,
701 unsigned int idx, int& pOut) const;
703 aiReturn Get(const char* pKey,unsigned int type,
704 unsigned int idx, ai_real& pOut) const;
706 aiReturn Get(const char* pKey,unsigned int type,
707 unsigned int idx, aiString& pOut) const;
709 aiReturn Get(const char* pKey,unsigned int type,
710 unsigned int idx, aiColor3D& pOut) const;
712 aiReturn Get(const char* pKey,unsigned int type,
713 unsigned int idx, aiColor4D& pOut) const;
715 aiReturn Get(const char* pKey,unsigned int type,
716 unsigned int idx, aiUVTransform& pOut) const;
718 // -------------------------------------------------------------------
719 /** Get the number of textures for a particular texture type.
720 * @param type Texture type to check for
721 * @return Number of textures for this type.
722 * @note A texture can be easily queried using #GetTexture() */
723 unsigned int GetTextureCount(aiTextureType type) const;
725 // -------------------------------------------------------------------
726 /** Helper function to get all parameters pertaining to a
727 * particular texture slot from a material.
728 *
729 * This function is provided just for convenience, you could also
730 * read the single material properties manually.
731 * @param type Specifies the type of the texture to be retrieved (
732 * e.g. diffuse, specular, height map ...)
733 * @param index Index of the texture to be retrieved. The function fails
734 * if there is no texture of that type with this index.
735 * #GetTextureCount() can be used to determine the number of textures
736 * per texture type.
737 * @param path Receives the path to the texture.
738 * If the texture is embedded, receives a '*' followed by the id of
739 * the texture (for the textures stored in the corresponding scene) which
740 * can be converted to an int using a function like atoi.
741 * NULL is a valid value.
742 * @param mapping The texture mapping.
743 * NULL is allowed as value.
744 * @param uvindex Receives the UV index of the texture.
745 * NULL is a valid value.
746 * @param blend Receives the blend factor for the texture
747 * NULL is a valid value.
748 * @param op Receives the texture operation to be performed between
749 * this texture and the previous texture. NULL is allowed as value.
750 * @param mapmode Receives the mapping modes to be used for the texture.
751 * The parameter may be NULL but if it is a valid pointer it MUST
752 * point to an array of 3 aiTextureMapMode's (one for each
753 * axis: UVW order (=XYZ)).
754 */
755 // -------------------------------------------------------------------
756 aiReturn GetTexture(aiTextureType type,
757 unsigned int index,
758 C_STRUCT aiString* path,
759 aiTextureMapping* mapping = NULL,
760 unsigned int* uvindex = NULL,
761 ai_real* blend = NULL,
762 aiTextureOp* op = NULL,
763 aiTextureMapMode* mapmode = NULL) const;
766 // Setters
769 // ------------------------------------------------------------------------------
770 /** @brief Add a property with a given key and type info to the material
771 * structure
772 *
773 * @param pInput Pointer to input data
774 * @param pSizeInBytes Size of input data
775 * @param pKey Key/Usage of the property (AI_MATKEY_XXX)
776 * @param type Set by the AI_MATKEY_XXX macro
777 * @param index Set by the AI_MATKEY_XXX macro
778 * @param pType Type information hint */
779 aiReturn AddBinaryProperty (const void* pInput,
780 unsigned int pSizeInBytes,
781 const char* pKey,
782 unsigned int type ,
783 unsigned int index ,
784 aiPropertyTypeInfo pType);
786 // ------------------------------------------------------------------------------
787 /** @brief Add a string property with a given key and type info to the
788 * material structure
789 *
790 * @param pInput Input string
791 * @param pKey Key/Usage of the property (AI_MATKEY_XXX)
792 * @param type Set by the AI_MATKEY_XXX macro
793 * @param index Set by the AI_MATKEY_XXX macro */
794 aiReturn AddProperty (const aiString* pInput,
795 const char* pKey,
796 unsigned int type = 0,
797 unsigned int index = 0);
799 // ------------------------------------------------------------------------------
800 /** @brief Add a property with a given key to the material structure
801 * @param pInput Pointer to the input data
802 * @param pNumValues Number of values in the array
803 * @param pKey Key/Usage of the property (AI_MATKEY_XXX)
804 * @param type Set by the AI_MATKEY_XXX macro
805 * @param index Set by the AI_MATKEY_XXX macro */
806 template<class TYPE>
807 aiReturn AddProperty (const TYPE* pInput,
808 unsigned int pNumValues,
809 const char* pKey,
810 unsigned int type = 0,
811 unsigned int index = 0);
813 aiReturn AddProperty (const aiVector3D* pInput,
814 unsigned int pNumValues,
815 const char* pKey,
816 unsigned int type = 0,
817 unsigned int index = 0);
819 aiReturn AddProperty (const aiColor3D* pInput,
820 unsigned int pNumValues,
821 const char* pKey,
822 unsigned int type = 0,
823 unsigned int index = 0);
825 aiReturn AddProperty (const aiColor4D* pInput,
826 unsigned int pNumValues,
827 const char* pKey,
828 unsigned int type = 0,
829 unsigned int index = 0);
831 aiReturn AddProperty (const int* pInput,
832 unsigned int pNumValues,
833 const char* pKey,
834 unsigned int type = 0,
835 unsigned int index = 0);
837 aiReturn AddProperty (const float* pInput,
838 unsigned int pNumValues,
839 const char* pKey,
840 unsigned int type = 0,
841 unsigned int index = 0);
843 aiReturn AddProperty (const double* pInput,
844 unsigned int pNumValues,
845 const char* pKey,
846 unsigned int type = 0,
847 unsigned int index = 0);
849 aiReturn AddProperty (const aiUVTransform* pInput,
850 unsigned int pNumValues,
851 const char* pKey,
852 unsigned int type = 0,
853 unsigned int index = 0);
855 // ------------------------------------------------------------------------------
856 /** @brief Remove a given key from the list.
857 *
858 * The function fails if the key isn't found
859 * @param pKey Key to be deleted
860 * @param type Set by the AI_MATKEY_XXX macro
861 * @param index Set by the AI_MATKEY_XXX macro */
862 aiReturn RemoveProperty (const char* pKey,
863 unsigned int type = 0,
864 unsigned int index = 0);
866 // ------------------------------------------------------------------------------
867 /** @brief Removes all properties from the material.
868 *
869 * The data array remains allocated so adding new properties is quite fast. */
870 void Clear();
872 // ------------------------------------------------------------------------------
873 /** Copy the property list of a material
874 * @param pcDest Destination material
875 * @param pcSrc Source material
876 */
877 static void CopyPropertyList(aiMaterial* pcDest,
878 const aiMaterial* pcSrc);
881 #endif
883 /** List of all material properties loaded. */
884 C_STRUCT aiMaterialProperty** mProperties;
886 /** Number of properties in the data base */
887 unsigned int mNumProperties;
889 /** Storage allocated */
890 unsigned int mNumAllocated;
891 };
893 // Go back to extern "C" again
894 #ifdef __cplusplus
895 extern "C" {
896 #endif
898 // ---------------------------------------------------------------------------
899 #define AI_MATKEY_NAME "?mat.name",0,0
900 #define AI_MATKEY_TWOSIDED "$mat.twosided",0,0
901 #define AI_MATKEY_SHADING_MODEL "$mat.shadingm",0,0
902 #define AI_MATKEY_ENABLE_WIREFRAME "$mat.wireframe",0,0
903 #define AI_MATKEY_BLEND_FUNC "$mat.blend",0,0
904 #define AI_MATKEY_OPACITY "$mat.opacity",0,0
905 #define AI_MATKEY_BUMPSCALING "$mat.bumpscaling",0,0
906 #define AI_MATKEY_SHININESS "$mat.shininess",0,0
907 #define AI_MATKEY_REFLECTIVITY "$mat.reflectivity",0,0
908 #define AI_MATKEY_SHININESS_STRENGTH "$mat.shinpercent",0,0
909 #define AI_MATKEY_REFRACTI "$mat.refracti",0,0
910 #define AI_MATKEY_COLOR_DIFFUSE "$clr.diffuse",0,0
911 #define AI_MATKEY_COLOR_AMBIENT "$clr.ambient",0,0
912 #define AI_MATKEY_COLOR_SPECULAR "$clr.specular",0,0
913 #define AI_MATKEY_COLOR_EMISSIVE "$clr.emissive",0,0
914 #define AI_MATKEY_COLOR_TRANSPARENT "$clr.transparent",0,0
915 #define AI_MATKEY_COLOR_REFLECTIVE "$clr.reflective",0,0
916 #define AI_MATKEY_GLOBAL_BACKGROUND_IMAGE "?bg.global",0,0
918 // ---------------------------------------------------------------------------
919 // Pure key names for all texture-related properties
920 //! @cond MATS_DOC_FULL
921 #define _AI_MATKEY_TEXTURE_BASE "$tex.file"
922 #define _AI_MATKEY_UVWSRC_BASE "$tex.uvwsrc"
923 #define _AI_MATKEY_TEXOP_BASE "$tex.op"
924 #define _AI_MATKEY_MAPPING_BASE "$tex.mapping"
925 #define _AI_MATKEY_TEXBLEND_BASE "$tex.blend"
926 #define _AI_MATKEY_MAPPINGMODE_U_BASE "$tex.mapmodeu"
927 #define _AI_MATKEY_MAPPINGMODE_V_BASE "$tex.mapmodev"
928 #define _AI_MATKEY_TEXMAP_AXIS_BASE "$tex.mapaxis"
929 #define _AI_MATKEY_UVTRANSFORM_BASE "$tex.uvtrafo"
930 #define _AI_MATKEY_TEXFLAGS_BASE "$tex.flags"
931 //! @endcond
933 // ---------------------------------------------------------------------------
934 #define AI_MATKEY_TEXTURE(type, N) _AI_MATKEY_TEXTURE_BASE,type,N
936 // For backward compatibility and simplicity
937 //! @cond MATS_DOC_FULL
938 #define AI_MATKEY_TEXTURE_DIFFUSE(N) \
939 AI_MATKEY_TEXTURE(aiTextureType_DIFFUSE,N)
941 #define AI_MATKEY_TEXTURE_SPECULAR(N) \
942 AI_MATKEY_TEXTURE(aiTextureType_SPECULAR,N)
944 #define AI_MATKEY_TEXTURE_AMBIENT(N) \
945 AI_MATKEY_TEXTURE(aiTextureType_AMBIENT,N)
947 #define AI_MATKEY_TEXTURE_EMISSIVE(N) \
948 AI_MATKEY_TEXTURE(aiTextureType_EMISSIVE,N)
950 #define AI_MATKEY_TEXTURE_NORMALS(N) \
951 AI_MATKEY_TEXTURE(aiTextureType_NORMALS,N)
953 #define AI_MATKEY_TEXTURE_HEIGHT(N) \
954 AI_MATKEY_TEXTURE(aiTextureType_HEIGHT,N)
956 #define AI_MATKEY_TEXTURE_SHININESS(N) \
957 AI_MATKEY_TEXTURE(aiTextureType_SHININESS,N)
959 #define AI_MATKEY_TEXTURE_OPACITY(N) \
960 AI_MATKEY_TEXTURE(aiTextureType_OPACITY,N)
962 #define AI_MATKEY_TEXTURE_DISPLACEMENT(N) \
963 AI_MATKEY_TEXTURE(aiTextureType_DISPLACEMENT,N)
965 #define AI_MATKEY_TEXTURE_LIGHTMAP(N) \
966 AI_MATKEY_TEXTURE(aiTextureType_LIGHTMAP,N)
968 #define AI_MATKEY_TEXTURE_REFLECTION(N) \
969 AI_MATKEY_TEXTURE(aiTextureType_REFLECTION,N)
971 //! @endcond
973 // ---------------------------------------------------------------------------
974 #define AI_MATKEY_UVWSRC(type, N) _AI_MATKEY_UVWSRC_BASE,type,N
976 // For backward compatibility and simplicity
977 //! @cond MATS_DOC_FULL
978 #define AI_MATKEY_UVWSRC_DIFFUSE(N) \
979 AI_MATKEY_UVWSRC(aiTextureType_DIFFUSE,N)
981 #define AI_MATKEY_UVWSRC_SPECULAR(N) \
982 AI_MATKEY_UVWSRC(aiTextureType_SPECULAR,N)
984 #define AI_MATKEY_UVWSRC_AMBIENT(N) \
985 AI_MATKEY_UVWSRC(aiTextureType_AMBIENT,N)
987 #define AI_MATKEY_UVWSRC_EMISSIVE(N) \
988 AI_MATKEY_UVWSRC(aiTextureType_EMISSIVE,N)
990 #define AI_MATKEY_UVWSRC_NORMALS(N) \
991 AI_MATKEY_UVWSRC(aiTextureType_NORMALS,N)
993 #define AI_MATKEY_UVWSRC_HEIGHT(N) \
994 AI_MATKEY_UVWSRC(aiTextureType_HEIGHT,N)
996 #define AI_MATKEY_UVWSRC_SHININESS(N) \
997 AI_MATKEY_UVWSRC(aiTextureType_SHININESS,N)
999 #define AI_MATKEY_UVWSRC_OPACITY(N) \
1000 AI_MATKEY_UVWSRC(aiTextureType_OPACITY,N)
1002 #define AI_MATKEY_UVWSRC_DISPLACEMENT(N) \
1003 AI_MATKEY_UVWSRC(aiTextureType_DISPLACEMENT,N)
1005 #define AI_MATKEY_UVWSRC_LIGHTMAP(N) \
1006 AI_MATKEY_UVWSRC(aiTextureType_LIGHTMAP,N)
1008 #define AI_MATKEY_UVWSRC_REFLECTION(N) \
1009 AI_MATKEY_UVWSRC(aiTextureType_REFLECTION,N)
1011 //! @endcond
1012 // ---------------------------------------------------------------------------
1013 #define AI_MATKEY_TEXOP(type, N) _AI_MATKEY_TEXOP_BASE,type,N
1015 // For backward compatibility and simplicity
1016 //! @cond MATS_DOC_FULL
1017 #define AI_MATKEY_TEXOP_DIFFUSE(N) \
1018 AI_MATKEY_TEXOP(aiTextureType_DIFFUSE,N)
1020 #define AI_MATKEY_TEXOP_SPECULAR(N) \
1021 AI_MATKEY_TEXOP(aiTextureType_SPECULAR,N)
1023 #define AI_MATKEY_TEXOP_AMBIENT(N) \
1024 AI_MATKEY_TEXOP(aiTextureType_AMBIENT,N)
1026 #define AI_MATKEY_TEXOP_EMISSIVE(N) \
1027 AI_MATKEY_TEXOP(aiTextureType_EMISSIVE,N)
1029 #define AI_MATKEY_TEXOP_NORMALS(N) \
1030 AI_MATKEY_TEXOP(aiTextureType_NORMALS,N)
1032 #define AI_MATKEY_TEXOP_HEIGHT(N) \
1033 AI_MATKEY_TEXOP(aiTextureType_HEIGHT,N)
1035 #define AI_MATKEY_TEXOP_SHININESS(N) \
1036 AI_MATKEY_TEXOP(aiTextureType_SHININESS,N)
1038 #define AI_MATKEY_TEXOP_OPACITY(N) \
1039 AI_MATKEY_TEXOP(aiTextureType_OPACITY,N)
1041 #define AI_MATKEY_TEXOP_DISPLACEMENT(N) \
1042 AI_MATKEY_TEXOP(aiTextureType_DISPLACEMENT,N)
1044 #define AI_MATKEY_TEXOP_LIGHTMAP(N) \
1045 AI_MATKEY_TEXOP(aiTextureType_LIGHTMAP,N)
1047 #define AI_MATKEY_TEXOP_REFLECTION(N) \
1048 AI_MATKEY_TEXOP(aiTextureType_REFLECTION,N)
1050 //! @endcond
1051 // ---------------------------------------------------------------------------
1052 #define AI_MATKEY_MAPPING(type, N) _AI_MATKEY_MAPPING_BASE,type,N
1054 // For backward compatibility and simplicity
1055 //! @cond MATS_DOC_FULL
1056 #define AI_MATKEY_MAPPING_DIFFUSE(N) \
1057 AI_MATKEY_MAPPING(aiTextureType_DIFFUSE,N)
1059 #define AI_MATKEY_MAPPING_SPECULAR(N) \
1060 AI_MATKEY_MAPPING(aiTextureType_SPECULAR,N)
1062 #define AI_MATKEY_MAPPING_AMBIENT(N) \
1063 AI_MATKEY_MAPPING(aiTextureType_AMBIENT,N)
1065 #define AI_MATKEY_MAPPING_EMISSIVE(N) \
1066 AI_MATKEY_MAPPING(aiTextureType_EMISSIVE,N)
1068 #define AI_MATKEY_MAPPING_NORMALS(N) \
1069 AI_MATKEY_MAPPING(aiTextureType_NORMALS,N)
1071 #define AI_MATKEY_MAPPING_HEIGHT(N) \
1072 AI_MATKEY_MAPPING(aiTextureType_HEIGHT,N)
1074 #define AI_MATKEY_MAPPING_SHININESS(N) \
1075 AI_MATKEY_MAPPING(aiTextureType_SHININESS,N)
1077 #define AI_MATKEY_MAPPING_OPACITY(N) \
1078 AI_MATKEY_MAPPING(aiTextureType_OPACITY,N)
1080 #define AI_MATKEY_MAPPING_DISPLACEMENT(N) \
1081 AI_MATKEY_MAPPING(aiTextureType_DISPLACEMENT,N)
1083 #define AI_MATKEY_MAPPING_LIGHTMAP(N) \
1084 AI_MATKEY_MAPPING(aiTextureType_LIGHTMAP,N)
1086 #define AI_MATKEY_MAPPING_REFLECTION(N) \
1087 AI_MATKEY_MAPPING(aiTextureType_REFLECTION,N)
1089 //! @endcond
1090 // ---------------------------------------------------------------------------
1091 #define AI_MATKEY_TEXBLEND(type, N) _AI_MATKEY_TEXBLEND_BASE,type,N
1093 // For backward compatibility and simplicity
1094 //! @cond MATS_DOC_FULL
1095 #define AI_MATKEY_TEXBLEND_DIFFUSE(N) \
1096 AI_MATKEY_TEXBLEND(aiTextureType_DIFFUSE,N)
1098 #define AI_MATKEY_TEXBLEND_SPECULAR(N) \
1099 AI_MATKEY_TEXBLEND(aiTextureType_SPECULAR,N)
1101 #define AI_MATKEY_TEXBLEND_AMBIENT(N) \
1102 AI_MATKEY_TEXBLEND(aiTextureType_AMBIENT,N)
1104 #define AI_MATKEY_TEXBLEND_EMISSIVE(N) \
1105 AI_MATKEY_TEXBLEND(aiTextureType_EMISSIVE,N)
1107 #define AI_MATKEY_TEXBLEND_NORMALS(N) \
1108 AI_MATKEY_TEXBLEND(aiTextureType_NORMALS,N)
1110 #define AI_MATKEY_TEXBLEND_HEIGHT(N) \
1111 AI_MATKEY_TEXBLEND(aiTextureType_HEIGHT,N)
1113 #define AI_MATKEY_TEXBLEND_SHININESS(N) \
1114 AI_MATKEY_TEXBLEND(aiTextureType_SHININESS,N)
1116 #define AI_MATKEY_TEXBLEND_OPACITY(N) \
1117 AI_MATKEY_TEXBLEND(aiTextureType_OPACITY,N)
1119 #define AI_MATKEY_TEXBLEND_DISPLACEMENT(N) \
1120 AI_MATKEY_TEXBLEND(aiTextureType_DISPLACEMENT,N)
1122 #define AI_MATKEY_TEXBLEND_LIGHTMAP(N) \
1123 AI_MATKEY_TEXBLEND(aiTextureType_LIGHTMAP,N)
1125 #define AI_MATKEY_TEXBLEND_REFLECTION(N) \
1126 AI_MATKEY_TEXBLEND(aiTextureType_REFLECTION,N)
1128 //! @endcond
1129 // ---------------------------------------------------------------------------
1130 #define AI_MATKEY_MAPPINGMODE_U(type, N) _AI_MATKEY_MAPPINGMODE_U_BASE,type,N
1132 // For backward compatibility and simplicity
1133 //! @cond MATS_DOC_FULL
1134 #define AI_MATKEY_MAPPINGMODE_U_DIFFUSE(N) \
1135 AI_MATKEY_MAPPINGMODE_U(aiTextureType_DIFFUSE,N)
1137 #define AI_MATKEY_MAPPINGMODE_U_SPECULAR(N) \
1138 AI_MATKEY_MAPPINGMODE_U(aiTextureType_SPECULAR,N)
1140 #define AI_MATKEY_MAPPINGMODE_U_AMBIENT(N) \
1141 AI_MATKEY_MAPPINGMODE_U(aiTextureType_AMBIENT,N)
1143 #define AI_MATKEY_MAPPINGMODE_U_EMISSIVE(N) \
1144 AI_MATKEY_MAPPINGMODE_U(aiTextureType_EMISSIVE,N)
1146 #define AI_MATKEY_MAPPINGMODE_U_NORMALS(N) \
1147 AI_MATKEY_MAPPINGMODE_U(aiTextureType_NORMALS,N)
1149 #define AI_MATKEY_MAPPINGMODE_U_HEIGHT(N) \
1150 AI_MATKEY_MAPPINGMODE_U(aiTextureType_HEIGHT,N)
1152 #define AI_MATKEY_MAPPINGMODE_U_SHININESS(N) \
1153 AI_MATKEY_MAPPINGMODE_U(aiTextureType_SHININESS,N)
1155 #define AI_MATKEY_MAPPINGMODE_U_OPACITY(N) \
1156 AI_MATKEY_MAPPINGMODE_U(aiTextureType_OPACITY,N)
1158 #define AI_MATKEY_MAPPINGMODE_U_DISPLACEMENT(N) \
1159 AI_MATKEY_MAPPINGMODE_U(aiTextureType_DISPLACEMENT,N)
1161 #define AI_MATKEY_MAPPINGMODE_U_LIGHTMAP(N) \
1162 AI_MATKEY_MAPPINGMODE_U(aiTextureType_LIGHTMAP,N)
1164 #define AI_MATKEY_MAPPINGMODE_U_REFLECTION(N) \
1165 AI_MATKEY_MAPPINGMODE_U(aiTextureType_REFLECTION,N)
1167 //! @endcond
1168 // ---------------------------------------------------------------------------
1169 #define AI_MATKEY_MAPPINGMODE_V(type, N) _AI_MATKEY_MAPPINGMODE_V_BASE,type,N
1171 // For backward compatibility and simplicity
1172 //! @cond MATS_DOC_FULL
1173 #define AI_MATKEY_MAPPINGMODE_V_DIFFUSE(N) \
1174 AI_MATKEY_MAPPINGMODE_V(aiTextureType_DIFFUSE,N)
1176 #define AI_MATKEY_MAPPINGMODE_V_SPECULAR(N) \
1177 AI_MATKEY_MAPPINGMODE_V(aiTextureType_SPECULAR,N)
1179 #define AI_MATKEY_MAPPINGMODE_V_AMBIENT(N) \
1180 AI_MATKEY_MAPPINGMODE_V(aiTextureType_AMBIENT,N)
1182 #define AI_MATKEY_MAPPINGMODE_V_EMISSIVE(N) \
1183 AI_MATKEY_MAPPINGMODE_V(aiTextureType_EMISSIVE,N)
1185 #define AI_MATKEY_MAPPINGMODE_V_NORMALS(N) \
1186 AI_MATKEY_MAPPINGMODE_V(aiTextureType_NORMALS,N)
1188 #define AI_MATKEY_MAPPINGMODE_V_HEIGHT(N) \
1189 AI_MATKEY_MAPPINGMODE_V(aiTextureType_HEIGHT,N)
1191 #define AI_MATKEY_MAPPINGMODE_V_SHININESS(N) \
1192 AI_MATKEY_MAPPINGMODE_V(aiTextureType_SHININESS,N)
1194 #define AI_MATKEY_MAPPINGMODE_V_OPACITY(N) \
1195 AI_MATKEY_MAPPINGMODE_V(aiTextureType_OPACITY,N)
1197 #define AI_MATKEY_MAPPINGMODE_V_DISPLACEMENT(N) \
1198 AI_MATKEY_MAPPINGMODE_V(aiTextureType_DISPLACEMENT,N)
1200 #define AI_MATKEY_MAPPINGMODE_V_LIGHTMAP(N) \
1201 AI_MATKEY_MAPPINGMODE_V(aiTextureType_LIGHTMAP,N)
1203 #define AI_MATKEY_MAPPINGMODE_V_REFLECTION(N) \
1204 AI_MATKEY_MAPPINGMODE_V(aiTextureType_REFLECTION,N)
1206 //! @endcond
1207 // ---------------------------------------------------------------------------
1208 #define AI_MATKEY_TEXMAP_AXIS(type, N) _AI_MATKEY_TEXMAP_AXIS_BASE,type,N
1210 // For backward compatibility and simplicity
1211 //! @cond MATS_DOC_FULL
1212 #define AI_MATKEY_TEXMAP_AXIS_DIFFUSE(N) \
1213 AI_MATKEY_TEXMAP_AXIS(aiTextureType_DIFFUSE,N)
1215 #define AI_MATKEY_TEXMAP_AXIS_SPECULAR(N) \
1216 AI_MATKEY_TEXMAP_AXIS(aiTextureType_SPECULAR,N)
1218 #define AI_MATKEY_TEXMAP_AXIS_AMBIENT(N) \
1219 AI_MATKEY_TEXMAP_AXIS(aiTextureType_AMBIENT,N)
1221 #define AI_MATKEY_TEXMAP_AXIS_EMISSIVE(N) \
1222 AI_MATKEY_TEXMAP_AXIS(aiTextureType_EMISSIVE,N)
1224 #define AI_MATKEY_TEXMAP_AXIS_NORMALS(N) \
1225 AI_MATKEY_TEXMAP_AXIS(aiTextureType_NORMALS,N)
1227 #define AI_MATKEY_TEXMAP_AXIS_HEIGHT(N) \
1228 AI_MATKEY_TEXMAP_AXIS(aiTextureType_HEIGHT,N)
1230 #define AI_MATKEY_TEXMAP_AXIS_SHININESS(N) \
1231 AI_MATKEY_TEXMAP_AXIS(aiTextureType_SHININESS,N)
1233 #define AI_MATKEY_TEXMAP_AXIS_OPACITY(N) \
1234 AI_MATKEY_TEXMAP_AXIS(aiTextureType_OPACITY,N)
1236 #define AI_MATKEY_TEXMAP_AXIS_DISPLACEMENT(N) \
1237 AI_MATKEY_TEXMAP_AXIS(aiTextureType_DISPLACEMENT,N)
1239 #define AI_MATKEY_TEXMAP_AXIS_LIGHTMAP(N) \
1240 AI_MATKEY_TEXMAP_AXIS(aiTextureType_LIGHTMAP,N)
1242 #define AI_MATKEY_TEXMAP_AXIS_REFLECTION(N) \
1243 AI_MATKEY_TEXMAP_AXIS(aiTextureType_REFLECTION,N)
1245 //! @endcond
1246 // ---------------------------------------------------------------------------
1247 #define AI_MATKEY_UVTRANSFORM(type, N) _AI_MATKEY_UVTRANSFORM_BASE,type,N
1249 // For backward compatibility and simplicity
1250 //! @cond MATS_DOC_FULL
1251 #define AI_MATKEY_UVTRANSFORM_DIFFUSE(N) \
1252 AI_MATKEY_UVTRANSFORM(aiTextureType_DIFFUSE,N)
1254 #define AI_MATKEY_UVTRANSFORM_SPECULAR(N) \
1255 AI_MATKEY_UVTRANSFORM(aiTextureType_SPECULAR,N)
1257 #define AI_MATKEY_UVTRANSFORM_AMBIENT(N) \
1258 AI_MATKEY_UVTRANSFORM(aiTextureType_AMBIENT,N)
1260 #define AI_MATKEY_UVTRANSFORM_EMISSIVE(N) \
1261 AI_MATKEY_UVTRANSFORM(aiTextureType_EMISSIVE,N)
1263 #define AI_MATKEY_UVTRANSFORM_NORMALS(N) \
1264 AI_MATKEY_UVTRANSFORM(aiTextureType_NORMALS,N)
1266 #define AI_MATKEY_UVTRANSFORM_HEIGHT(N) \
1267 AI_MATKEY_UVTRANSFORM(aiTextureType_HEIGHT,N)
1269 #define AI_MATKEY_UVTRANSFORM_SHININESS(N) \
1270 AI_MATKEY_UVTRANSFORM(aiTextureType_SHININESS,N)
1272 #define AI_MATKEY_UVTRANSFORM_OPACITY(N) \
1273 AI_MATKEY_UVTRANSFORM(aiTextureType_OPACITY,N)
1275 #define AI_MATKEY_UVTRANSFORM_DISPLACEMENT(N) \
1276 AI_MATKEY_UVTRANSFORM(aiTextureType_DISPLACEMENT,N)
1278 #define AI_MATKEY_UVTRANSFORM_LIGHTMAP(N) \
1279 AI_MATKEY_UVTRANSFORM(aiTextureType_LIGHTMAP,N)
1281 #define AI_MATKEY_UVTRANSFORM_REFLECTION(N) \
1282 AI_MATKEY_UVTRANSFORM(aiTextureType_REFLECTION,N)
1284 #define AI_MATKEY_UVTRANSFORM_UNKNOWN(N) \
1285 AI_MATKEY_UVTRANSFORM(aiTextureType_UNKNOWN,N)
1287 //! @endcond
1288 // ---------------------------------------------------------------------------
1289 #define AI_MATKEY_TEXFLAGS(type, N) _AI_MATKEY_TEXFLAGS_BASE,type,N
1291 // For backward compatibility and simplicity
1292 //! @cond MATS_DOC_FULL
1293 #define AI_MATKEY_TEXFLAGS_DIFFUSE(N) \
1294 AI_MATKEY_TEXFLAGS(aiTextureType_DIFFUSE,N)
1296 #define AI_MATKEY_TEXFLAGS_SPECULAR(N) \
1297 AI_MATKEY_TEXFLAGS(aiTextureType_SPECULAR,N)
1299 #define AI_MATKEY_TEXFLAGS_AMBIENT(N) \
1300 AI_MATKEY_TEXFLAGS(aiTextureType_AMBIENT,N)
1302 #define AI_MATKEY_TEXFLAGS_EMISSIVE(N) \
1303 AI_MATKEY_TEXFLAGS(aiTextureType_EMISSIVE,N)
1305 #define AI_MATKEY_TEXFLAGS_NORMALS(N) \
1306 AI_MATKEY_TEXFLAGS(aiTextureType_NORMALS,N)
1308 #define AI_MATKEY_TEXFLAGS_HEIGHT(N) \
1309 AI_MATKEY_TEXFLAGS(aiTextureType_HEIGHT,N)
1311 #define AI_MATKEY_TEXFLAGS_SHININESS(N) \
1312 AI_MATKEY_TEXFLAGS(aiTextureType_SHININESS,N)
1314 #define AI_MATKEY_TEXFLAGS_OPACITY(N) \
1315 AI_MATKEY_TEXFLAGS(aiTextureType_OPACITY,N)
1317 #define AI_MATKEY_TEXFLAGS_DISPLACEMENT(N) \
1318 AI_MATKEY_TEXFLAGS(aiTextureType_DISPLACEMENT,N)
1320 #define AI_MATKEY_TEXFLAGS_LIGHTMAP(N) \
1321 AI_MATKEY_TEXFLAGS(aiTextureType_LIGHTMAP,N)
1323 #define AI_MATKEY_TEXFLAGS_REFLECTION(N) \
1324 AI_MATKEY_TEXFLAGS(aiTextureType_REFLECTION,N)
1326 #define AI_MATKEY_TEXFLAGS_UNKNOWN(N) \
1327 AI_MATKEY_TEXFLAGS(aiTextureType_UNKNOWN,N)
1329 //! @endcond
1330 //!
1331 // ---------------------------------------------------------------------------
1332 /** @brief Retrieve a material property with a specific key from the material
1333 *
1334 * @param pMat Pointer to the input material. May not be NULL
1335 * @param pKey Key to search for. One of the AI_MATKEY_XXX constants.
1336 * @param type Specifies the type of the texture to be retrieved (
1337 * e.g. diffuse, specular, height map ...)
1338 * @param index Index of the texture to be retrieved.
1339 * @param pPropOut Pointer to receive a pointer to a valid aiMaterialProperty
1340 * structure or NULL if the key has not been found. */
1341 // ---------------------------------------------------------------------------
1342 ASSIMP_API C_ENUM aiReturn aiGetMaterialProperty(
1343 const C_STRUCT aiMaterial* pMat,
1344 const char* pKey,
1345 unsigned int type,
1346 unsigned int index,
1347 const C_STRUCT aiMaterialProperty** pPropOut);
1349 // ---------------------------------------------------------------------------
1350 /** @brief Retrieve an array of float values with a specific key
1351 * from the material
1352 *
1353 * Pass one of the AI_MATKEY_XXX constants for the last three parameters (the
1354 * example reads the #AI_MATKEY_UVTRANSFORM property of the first diffuse texture)
1355 * @code
1356 * aiUVTransform trafo;
1357 * unsigned int max = sizeof(aiUVTransform);
1358 * if (AI_SUCCESS != aiGetMaterialFloatArray(mat, AI_MATKEY_UVTRANSFORM(aiTextureType_DIFFUSE,0),
1359 * (float*)&trafo, &max) || sizeof(aiUVTransform) != max)
1360 * {
1361 * // error handling
1362 * }
1363 * @endcode
1364 *
1365 * @param pMat Pointer to the input material. May not be NULL
1366 * @param pKey Key to search for. One of the AI_MATKEY_XXX constants.
1367 * @param pOut Pointer to a buffer to receive the result.
1368 * @param pMax Specifies the size of the given buffer, in float's.
1369 * Receives the number of values (not bytes!) read.
1370 * @param type (see the code sample above)
1371 * @param index (see the code sample above)
1372 * @return Specifies whether the key has been found. If not, the output
1373 * arrays remains unmodified and pMax is set to 0.*/
1374 // ---------------------------------------------------------------------------
1375 ASSIMP_API C_ENUM aiReturn aiGetMaterialFloatArray(
1376 const C_STRUCT aiMaterial* pMat,
1377 const char* pKey,
1378 unsigned int type,
1379 unsigned int index,
1380 ai_real* pOut,
1381 unsigned int* pMax);
1384 #ifdef __cplusplus
1386 // ---------------------------------------------------------------------------
1387 /** @brief Retrieve a single float property with a specific key from the material.
1388 *
1389 * Pass one of the AI_MATKEY_XXX constants for the last three parameters (the
1390 * example reads the #AI_MATKEY_SHININESS_STRENGTH property of the first diffuse texture)
1391 * @code
1392 * float specStrength = 1.f; // default value, remains unmodified if we fail.
1393 * aiGetMaterialFloat(mat, AI_MATKEY_SHININESS_STRENGTH,
1394 * (float*)&specStrength);
1395 * @endcode
1396 *
1397 * @param pMat Pointer to the input material. May not be NULL
1398 * @param pKey Key to search for. One of the AI_MATKEY_XXX constants.
1399 * @param pOut Receives the output float.
1400 * @param type (see the code sample above)
1401 * @param index (see the code sample above)
1402 * @return Specifies whether the key has been found. If not, the output
1403 * float remains unmodified.*/
1404 // ---------------------------------------------------------------------------
1405 inline aiReturn aiGetMaterialFloat(const aiMaterial* pMat,
1406 const char* pKey,
1407 unsigned int type,
1408 unsigned int index,
1409 ai_real* pOut)
1410 {
1411 return aiGetMaterialFloatArray(pMat,pKey,type,index,pOut,(unsigned int*)0x0);
1412 }
1414 #else
1416 // Use our friend, the C preprocessor
1417 #define aiGetMaterialFloat (pMat, type, index, pKey, pOut) \
1418 aiGetMaterialFloatArray(pMat, type, index, pKey, pOut, NULL)
1420 #endif //!__cplusplus
1423 // ---------------------------------------------------------------------------
1424 /** @brief Retrieve an array of integer values with a specific key
1425 * from a material
1426 *
1427 * See the sample for aiGetMaterialFloatArray for more information.*/
1428 ASSIMP_API C_ENUM aiReturn aiGetMaterialIntegerArray(const C_STRUCT aiMaterial* pMat,
1429 const char* pKey,
1430 unsigned int type,
1431 unsigned int index,
1432 int* pOut,
1433 unsigned int* pMax);
1436 #ifdef __cplusplus
1438 // ---------------------------------------------------------------------------
1439 /** @brief Retrieve an integer property with a specific key from a material
1440 *
1441 * See the sample for aiGetMaterialFloat for more information.*/
1442 // ---------------------------------------------------------------------------
1443 inline aiReturn aiGetMaterialInteger(const C_STRUCT aiMaterial* pMat,
1444 const char* pKey,
1445 unsigned int type,
1446 unsigned int index,
1447 int* pOut)
1448 {
1449 return aiGetMaterialIntegerArray(pMat,pKey,type,index,pOut,(unsigned int*)0x0);
1450 }
1452 #else
1454 // use our friend, the C preprocessor
1455 #define aiGetMaterialInteger (pMat, type, index, pKey, pOut) \
1456 aiGetMaterialIntegerArray(pMat, type, index, pKey, pOut, NULL)
1458 #endif //!__cplusplus
1462 // ---------------------------------------------------------------------------
1463 /** @brief Retrieve a color value from the material property table
1464 *
1465 * See the sample for aiGetMaterialFloat for more information*/
1466 // ---------------------------------------------------------------------------
1467 ASSIMP_API C_ENUM aiReturn aiGetMaterialColor(const C_STRUCT aiMaterial* pMat,
1468 const char* pKey,
1469 unsigned int type,
1470 unsigned int index,
1471 C_STRUCT aiColor4D* pOut);
1474 // ---------------------------------------------------------------------------
1475 /** @brief Retrieve a aiUVTransform value from the material property table
1476 *
1477 * See the sample for aiGetMaterialFloat for more information*/
1478 // ---------------------------------------------------------------------------
1479 ASSIMP_API C_ENUM aiReturn aiGetMaterialUVTransform(const C_STRUCT aiMaterial* pMat,
1480 const char* pKey,
1481 unsigned int type,
1482 unsigned int index,
1483 C_STRUCT aiUVTransform* pOut);
1486 // ---------------------------------------------------------------------------
1487 /** @brief Retrieve a string from the material property table
1488 *
1489 * See the sample for aiGetMaterialFloat for more information.*/
1490 // ---------------------------------------------------------------------------
1491 ASSIMP_API C_ENUM aiReturn aiGetMaterialString(const C_STRUCT aiMaterial* pMat,
1492 const char* pKey,
1493 unsigned int type,
1494 unsigned int index,
1495 C_STRUCT aiString* pOut);
1497 // ---------------------------------------------------------------------------
1498 /** Get the number of textures for a particular texture type.
1499 * @param[in] pMat Pointer to the input material. May not be NULL
1500 * @param type Texture type to check for
1501 * @return Number of textures for this type.
1502 * @note A texture can be easily queried using #aiGetMaterialTexture() */
1503 // ---------------------------------------------------------------------------
1504 ASSIMP_API unsigned int aiGetMaterialTextureCount(const C_STRUCT aiMaterial* pMat,
1505 C_ENUM aiTextureType type);
1507 // ---------------------------------------------------------------------------
1508 /** @brief Helper function to get all values pertaining to a particular
1509 * texture slot from a material structure.
1510 *
1511 * This function is provided just for convenience. You could also read the
1512 * texture by parsing all of its properties manually. This function bundles
1513 * all of them in a huge function monster.
1514 *
1515 * @param[in] mat Pointer to the input material. May not be NULL
1516 * @param[in] type Specifies the texture stack to read from (e.g. diffuse,
1517 * specular, height map ...).
1518 * @param[in] index Index of the texture. The function fails if the
1519 * requested index is not available for this texture type.
1520 * #aiGetMaterialTextureCount() can be used to determine the number of
1521 * textures in a particular texture stack.
1522 * @param[out] path Receives the output path
1523 * If the texture is embedded, receives a '*' followed by the id of
1524 * the texture (for the textures stored in the corresponding scene) which
1525 * can be converted to an int using a function like atoi.
1526 * This parameter must be non-null.
1527 * @param mapping The texture mapping mode to be used.
1528 * Pass NULL if you're not interested in this information.
1529 * @param[out] uvindex For UV-mapped textures: receives the index of the UV
1530 * source channel. Unmodified otherwise.
1531 * Pass NULL if you're not interested in this information.
1532 * @param[out] blend Receives the blend factor for the texture
1533 * Pass NULL if you're not interested in this information.
1534 * @param[out] op Receives the texture blend operation to be perform between
1535 * this texture and the previous texture.
1536 * Pass NULL if you're not interested in this information.
1537 * @param[out] mapmode Receives the mapping modes to be used for the texture.
1538 * Pass NULL if you're not interested in this information. Otherwise,
1539 * pass a pointer to an array of two aiTextureMapMode's (one for each
1540 * axis, UV order).
1541 * @param[out] flags Receives the the texture flags.
1542 * @return AI_SUCCESS on success, otherwise something else. Have fun.*/
1543 // ---------------------------------------------------------------------------
1544 #ifdef __cplusplus
1545 ASSIMP_API aiReturn aiGetMaterialTexture(const C_STRUCT aiMaterial* mat,
1546 aiTextureType type,
1547 unsigned int index,
1548 aiString* path,
1549 aiTextureMapping* mapping = NULL,
1550 unsigned int* uvindex = NULL,
1551 ai_real* blend = NULL,
1552 aiTextureOp* op = NULL,
1553 aiTextureMapMode* mapmode = NULL,
1554 unsigned int* flags = NULL);
1555 #else
1556 C_ENUM aiReturn aiGetMaterialTexture(const C_STRUCT aiMaterial* mat,
1557 C_ENUM aiTextureType type,
1558 unsigned int index,
1559 C_STRUCT aiString* path,
1560 C_ENUM aiTextureMapping* mapping /*= NULL*/,
1561 unsigned int* uvindex /*= NULL*/,
1562 ai_real* blend /*= NULL*/,
1563 C_ENUM aiTextureOp* op /*= NULL*/,
1564 C_ENUM aiTextureMapMode* mapmode /*= NULL*/,
1565 unsigned int* flags /*= NULL*/);
1566 #endif // !#ifdef __cplusplus
1569 #ifdef __cplusplus
1570 }
1572 #include "material.inl"
1574 #endif //!__cplusplus
1576 #endif //!!AI_MATERIAL_H_INC