///////////////////////////////////////////////////////////////////////////////
// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance").
// All rights reserved.
//
// This software and its documentation and related materials are owned by
// the Alliance. The software may only be incorporated into application
// programs owned by members of the Alliance, subject to a signed
// Membership Agreement and Supplemental Software License Agreement with the
// Alliance. The structure and organization of this software are the valuable
// trade secrets of the Alliance and its suppliers. The software is also
// protected by copyright law and international treaty provisions. Application
// programs incorporating this software must include the following statement
// with their copyright notices:
//
// This application incorporates Open Design Alliance software pursuant to a license
// agreement with Open Design Alliance.
// Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance.
// All rights reserved.
//
// By use of this software, its documentation or related materials, you
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////
#ifndef _ODTV_MATERIAL_H_INCLUDED_
#define _ODTV_MATERIAL_H_INCLUDED_
#include "Tv.h"
#include "TvAttributeResolver.h"
#include "TvIObject.h"
#include "TvUserData.h"
class OdTvMaterialColor;
class OdTvMaterialMap;
class OdTvColorDef;
class OdTvMaterialId;
/** \details
The abstract interface class that implements handling of material entities supported by ODA Visualize SDK.
\sa
*/
class ODTV_EXPORT OdTvMaterial : public OdTvHandledIObject
{
public:
/** \details
Types of the using visual style specular factor
*/
enum VisualStyleSpecular
{
kNone = 0, // not using visual style specular factor (material factor is used instead instead)
kOverride = 1, // use incoming specular factor instead of material or visual style specular factors
kUseVisualStyleSpecular = 2 // use visual style specular factor
};
/** \details
Specifies the luminance modes.
*/
enum LuminanceMode
{
kSelfIllumination = 0, // Compute luminance from self-illumination parameters
kEmissionColor = 1 // Compute luminance using an emission material channel
};
/** \details
Contains declarations which define types of reflectivity.
*/
enum ReflectivityType
{
kReflectDefault = 0, // Default reflection (only reflectivity without texture or simple texture)
kReflectScene = 1, // Reflect scene objects (only for plane objects)
kReflectEnvironment = 2, // Reflect environment background
kReflectTexture = 3 // Reflect custom texture
};
/** \details
Specifies the normal maps processing method.
*/
enum NormalMapMethod
{
kTangentSpace, // Method of tangent spaces is used to compute the normal map.
kReliefPattern // Handle normal map as relief pattern material channel.
};
/** \details
Sets a new name for the material object.
\param sName [in] A string that contains the new material object's name.
\returns A value of type that contains the result of the operation.
\remarks
The name string length should be from 0 to 255 characters.
The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
underscores, and some special characters, but cannot contain inadmissible letters
("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
If the new material object name was successfully returned, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setName(const OdString& sName) = 0;
/** \details
Retrieves the current material object's name.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns A string that contains the name of the material object.
\remarks
If the rc parameter is not null and the name was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
*/
virtual OdString getName(OdTvResult* rc = NULL) const = 0;
/** \details
Sets a new description for the material object.
It can be a comment or series of underscores, dots, dashes, and spaces to reflect the representation of the material.
The initial value is an empty string.
\param sDescription [in] A string that contains the description.
\returns A value of type that contains the result of the operation.
\remarks
If the new material object description was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setDescription(const OdString& sDescription) = 0;
/** \details
Retrieves the current material object's description.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns A string that contains the description of the material object.
\remarks
If the rc parameter is not null and the description was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
*/
virtual OdString getDescription(OdTvResult* rc = NULL) const = 0;
/** \details
Sets a new ambient (shadow) color for the material object.
\param ambientColor [in] A new ambient color to be set.
\returns A value of type that contains the result of the operation.
\remarks
If the new ambient color was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setAmbient(const OdTvMaterialColor& ambientColor) = 0;
/** \details
Retrieves the current ambient (shadow) color of the material object.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns An object that contains the current ambient color.
\remarks
If the rc parameter is not null and the ambient color was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
*/
virtual OdTvMaterialColor getAmbient(OdTvResult* rc = NULL) const = 0;
/** \details
Sets a new diffuse (main) color for the material object.
\param diffuseColor [in] A new diffuse color to be set.
\param diffuseMap [in] A diffuse map, according to which a material is applied.
\returns A value of type that contains the result of the operation.
\remarks
If the new diffuse color was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setDiffuse(const OdTvMaterialColor& diffuseColor, const OdTvMaterialMap& diffuseMap) = 0;
/** \details
Retrieves the current diffuse (main) color of the material object.
\param diffuseColor [out] A placeholder for an object that represents the current diffuse color.
\param diffuseMap [out] A placeholder for an object that represents the current diffuse material map.
\returns A value of type that contains the result of the operation.
\remarks
The method fills the passed color and material map objects and returns them to a calling subroutine.
If the current diffuse color and diffuse map were successfully returned, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult getDiffuse(OdTvMaterialColor& diffuseColor, OdTvMaterialMap& diffuseMap) const = 0;
/** \details
Sets a new specular (reflection) color for the material object.
\param specularColor [in] A new specular color to be set.
\param dGlossFactor [in] A new value of the gloss factor.
\returns A value of type that contains the result of the operation.
\remarks
If the new specular color and gloss factor were successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setSpecular(const OdTvMaterialColor& specularColor, double dGlossFactor) = 0;
/** \details
Retrieves the current specular (reflection) color and gloss factor value of the material object.
\param specularColor [out] A placeholder for an object that represents the current specular color.
\param dGlossFactor [out] A placeholder for a gloss factor value.
\returns A value of type that contains the result of the operation.
\remarks
The method fills the passed color object and gloss factor placeholders and returns them to a calling subroutine.
If the current specular color and gloss factor were successfully returned, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult getSpecular(OdTvMaterialColor& specularColor, double& dGlossFactor) const = 0;
/** \details
Sets a new specular (reflection) color for the material object.
\param specularColor [in] A new specular color to be set.
\param specularMap [in] A specularMap map, according to which a material is applied.
\param dGlossFactor [in] A new value of the gloss factor.
\returns A value of type that contains the result of the operation.
\remarks
If the new specular color and gloss factor were successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setSpecular(const OdTvMaterialColor& specularColor, const OdTvMaterialMap& specularMap, double dGlossFactor) = 0;
/** \details
Retrieves the current specular (reflection) color and gloss factor value of the material object.
\param specularColor [out] A placeholder for an object that represents the current specular color.
\param specularMap [out] A placeholder for an object that represents the current specular material map.
\param dGlossFactor [out] A placeholder for a gloss factor value.
\returns A value of type that contains the result of the operation.
\remarks
The method fills the passed color object and gloss factor placeholders and returns them to a calling subroutine.
If the current specular color and gloss factor were successfully returned, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult getSpecular(OdTvMaterialColor& specularColor, OdTvMaterialMap& specularMap, double& dGlossFactor) const = 0;
/** \details
Sets a new emission (glow) color for the material object.
\param emissionColor [in] A new emission color to be set.
\param emissionMap [in] An emission map, according to which a material is applied.
\returns A value of type that contains the result of the operation.
\remarks
If the new emission color was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setEmission(const OdTvMaterialColor& emissionColor, const OdTvMaterialMap& emissionMap) = 0;
/** \details
Retrieves the current emission (glow) color of the material object.
\param emissionMap [out] A placeholder for an object that represents the current diffuse material map.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns An object that contains the current emission color.
\remarks
If the rc parameter is not null and the current emission color was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
*/
virtual OdTvMaterialColor getEmission(OdTvMaterialMap& emissionMap, OdTvResult* rc = NULL) const = 0;
/** \details
Sets the luminance mode for the material object.
\param mode [in] Luminance mode.
\returns A value of type that contains the result of the operation.
\remarks
If the new luminance mode was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setLuminanceMode(LuminanceMode mode) = 0;
/** \details
Retrieves the current luminance mode of the material object.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns A value that indicates type of the luminance mode.
\remarks
If the rc parameter is not null and the current luminance mode was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
*/
virtual LuminanceMode getLuminanceMode(OdTvResult* rc = NULL) const = 0;
/** \details
Sets a new specular gloss value for the material object.
\param dSpecularGloss [in] A new specular gloss to be set.
\returns A value of type that contains the result of the operation.
\remarks
If the new specular gloss value was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setSpecularGloss(double dSpecularGloss) = 0;
/** \details
Retrieves the current specular gloss value of the material object.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns The current specular gloss value.
\remarks
If the rc parameter is not null and the current specular gloss was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
*/
virtual double getSpecularGloss(OdTvResult* rc = NULL) const = 0;
/** \details
Sets a new opacity value for this material object.
\param dOpacityPercentage [in] A new opacity value to be set.
\param pOpacityMap [in] A new opacity map to be set.
\returns A value of type that contains the result of the operation.
\remarks
The opacity value varies from 0 (transparent) to 1 (non-transparent).
If pOpacityMap is NULL, opacity value will be used.
If the new opacity value was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setOpacity(double dOpacityPercentage, const OdTvMaterialMap* pOpacityMap = NULL) = 0;
/** \details
Retrieves the current opacity value of the material object.
\param opacityPercent [out] Opacity value.
\param opacityMap [out] A placeholder for an object that represents the current opacity material map.
\returns A value of type that contains the result of the operation.
\remarks
The method fills the passed value and material map objects and returns them to a calling subroutine.
The opacity value varies from 0 (transparent) to 1 (non-transparent).
If the current opacity value and opacity map were successfully returned, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult getOpacity(double& opacityPercent, OdTvMaterialMap& opacityMap) const = 0;
/** \details
Sets the bump component of this Material object.
\param bumpMap [in] A new bump map.
\returns A value of type that contains the result of the operation.
\remarks
If the new bump map was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setBump(const OdTvMaterialMap& bumpMap) = 0;
/** \details
Returns the bump component of this Material object.
\param bumpMap [out] Receives the bump map.
\returns A value of type that contains the result of the operation.
*/
virtual OdTvResult getBump(OdTvMaterialMap& bumpMap) const = 0;
/** \details
Sets the tint component of this Material object.
\param tintColor [in] A new tint color.
\param bEnable [in] Enables or disabled tint material channel.
\returns A value of type that contains the result of the operation.
\remarks
If the new tint color was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setTint(const OdTvMaterialColor &tintColor, bool bEnable = true) = 0;
/** \details
Returns the tint component of this Material object.
\param tintColor [out] Receives the tint color.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns true in case if tint material channel enabled or false elsewhere.
\remarks
If the rc parameter is not null and the current tint color was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
*/
virtual bool getTint(OdTvMaterialColor &tintColor, OdTvResult *rc = NULL) const = 0;
/** \details
Sets the reflectivity of this Material object.
\param reflectivity [in] A new reflectivity in a range [0;1].
\param type [in] Reflectivity type.
\param textureSourceFileName [in] Reflection texture source file name. Used only for kReflectTexture reflectivity type.
\returns A value of type that contains the result of the operation.
\remarks
If the new reflectivity was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setReflectivity(double reflectivity, ReflectivityType type = kReflectDefault, OdString textureSourceFileName = OdString()) = 0;
/** \details
Returns the reflectivity component of this Material object.
\param reflectivity [out] Receives the reflectivity value.
\param type [out] Receives the reflectivity type.
\param textureSourceFileName [out] Receives the reflection texture source file name. Used only for kReflectTexture reflectivity type.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns true in case if reflectivity material channel enabled or false otherwise.
*/
virtual OdTvResult getReflectivity(double& reflectivity, ReflectivityType& type, OdString* textureSourceFileName = NULL) const = 0;
/** \details
Sets the softness (blur amount) of the reflectivity texture.
\param softness [in] Softness coefficient. The recommended value should be in the range [0; 16].
\returns A value of type that contains the result of the operation.
\remarks
If the new reflectivity was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
This parameter is actual only for kReflectScene reflectivity type.
*/
virtual OdTvResult setReflectivitySoftness(OdUInt8 softness) = 0;
/** \details
Returns the softness (blur amount) of the reflectivity texture of this Material object.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns A softness (blur amount) of the reflectivity texture.
\remarks
If the rc parameter is not null and the softness of the reflectivity texture was successfully returned, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
*/
virtual OdUInt8 getReflectivitySoftness(OdTvResult* rc = NULL) const = 0;
/** \details
Sets a new secondary ambient (shadow) color for the material object.
\param ambientColor [in] A new to be set.
\returns A value of type that contains the result of the operation.
\remarks
If the new secondary ambient color was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
Using this method makes sense only if non-texture mode support is enabled by the setSupportNonTextureMode() method.
*/
virtual OdTvResult setSecondaryAmbient(const OdTvMaterialColor& ambientColor) = 0;
/** \details
Retrieves the current secondary ambient (shadow) color of the material object.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns A object that represents the current secondary ambient color.
\remarks
If the rc parameter is not null and the current secondary ambient (shadow) color was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
*/
virtual OdTvMaterialColor getSecondaryAmbient(OdTvResult* rc = NULL) const = 0;
/** \details
Sets a new secondary diffuse color for the material object.
\param diffuseColor [in] A new to be set.
\returns A value of type that contains the result of the operation.
\remarks
If the new secondary diffuse color was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
Using this method makes sense only if non-texture mode support is enabled by the setSupportNonTextureMode() method.
*/
virtual OdTvResult setSecondaryDiffuse(const OdTvMaterialColor& diffuseColor) = 0;
/** \details
Retrieves the current secondary diffuse color of the material object.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns A object that represents the current secondary diffuse color.
\remarks
If the rc parameter is not null and the current secondary diffuse color was successfully returned, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
*/
virtual OdTvMaterialColor getSecondaryDiffuse(OdTvResult* rc = NULL) const = 0;
/** \details
Sets a new secondary specular (reflection) for the material object.
\param specularColor [in] A new to be set.
\returns A value of type that contains the result of the operation.
\remarks
If the new secondary specular (reflection) was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
Using this method makes sense only if non-texture mode support is enabled by the setSupportNonTextureMode() method.
*/
virtual OdTvResult setSecondarySpecular(const OdTvMaterialColor& specularColor) = 0;
/** \details
Retrieves the current secondary specular (reflection) of the material object.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns A object that represents the current secondary specular (reflection) color.
\remarks
If the rc parameter is not null and the current secondary specular (reflection) was successfully returned, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
*/
virtual OdTvMaterialColor getSecondarySpecular(OdTvResult* rc = NULL) const = 0;
/** \details
Sets a new secondary opacity value for the material object.
\param opacityPercentage [in] A new opacity value to be set.
\returns A value of type that contains the result of the operation.
\remarks
The opacity value varies from 0 (transparent) to 1 (non-transparent).
If the new secondary opacity value was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
Using this method makes sense only if non-texture mode support is enabled by the setSupportNonTextureMode() method.
*/
virtual OdTvResult setSecondaryOpacity(double opacityPercentage) = 0;
/** \details
Retrieves the current secondary opacity value of the material object.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns The current secondary opacity value.
\remarks
The opacity value varies from 0 (transparent) to 1 (non-transparent).
If the rc parameter is not null and the current secondary opacity value was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
*/
virtual double getSecondaryOpacity(OdTvResult* rc = NULL) const = 0;
/** \details
Enables or disables non-texture mode support for the material object.
\param bNonTextureMode [in] A new support flag value.
\returns A value of type that contains the result of the operation.
\remarks
If the parameter passed to the method is equal to true, non-texture mode support is enabled;
otherwise (if the parameter is equal to false) non-texture mode support is disabled.
Using this method makes sense only if materials are disabled for the current visual style.
If non-texture mode support was successfully enabled or disabled, the method returns the tvOk value;
otherwise it returns an appropriate error code.
*/
virtual OdTvResult setSupportNonTextureMode(bool bNonTextureMode) = 0;
/** \details
Retrieves whether non-texture mode support is enabled for the material object.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns true if non-texture mode support is enabled; otherwise the method returns false.
\remarks
If the rc parameter is not null and the current value of the non-texture mode support flag was successfully returned, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
*/
virtual bool getSupportNonTextureMode(OdTvResult* rc = NULL) const = 0;
/** \details
Sets coefficient of opacity influence onto received shadows.
\param dShadowsOpacityEffect [in] Coefficient in 0.0-1.0 range.
\param dNonShadowLightsMergeEffect [in] Value in 0.0-1.0 range that influences ignoring shadows casting by lights.
\returns A value of type that contains the result of the operation.
\remarks
The effect percentage value varies from 0 to 1.
If dNonShadowLightsMergeEffect is 0.0 lights can cast shadows on the material, if dNonShadowLightsMergeEffect is 1.0 - lights do not cast shadows on the material.
If the new shadows opacity effect and shadow lights merge effect values were successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setShadowsOpacityEffect(double dShadowsOpacityEffect, double dNonShadowLightsMergeEffect = 1.0) = 0;
/** \details
Returns coefficient of opacity influence onto received shadows.
\param dNonShadowLightsMergeEffect [out] Receives a value in 0.0-1.0 range that influences ignoring shadows casting by lights.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns The current shadows opacity effect value.
\remarks
Coefficient set to 1.0 by default, which is means that shadows opacity fully depends from material opacity.
*/
virtual double getShadowsOpacityEffect(double* dNonShadowLightsMergeEffect = NULL, OdTvResult* rc = NULL) const = 0;
/** \details
Sets the overriding rule for the specular highlighting
\param flag [in] New value for the flag which indicates type of the specular highlighting overrride
\param dMaxSpecularFactor [in] Maximal specular highlighting factor. Varies from 0.01 to 1.
\returns A value of type that contains the result of the operation.
\remarks
If flag value is kNone, only own material specular value will be used.
If flag value is kOverride, the incoming value will be used.
If flag value is kUseVisualStyleSpecular, the rule will be the next:
Final specular parameter should be in the range [1;128]. The maximal specular factor (dMaxSpecularFactor)
allows to vary this range. When the maximal specular factor is equal to 1, the final specular parameter will be in the range of [1;128]
(for the value in Visual style equal to 0% the final specular parameter will 128, for the value in Visual style equal to 100% the final specular parameter will 1).
When the maximal specular factor is equal to 0.5, the final specular parameter will be in the range of [1;64]
(for the value in Visual style equal to 0% the final specular parameter will 64, for the value in Visual style equal to 100% the final specular parameter will 1). And so on.
*/
virtual OdTvResult setUseVisualStyleSpecular(VisualStyleSpecular flag, double dMaxSpecularFactor = 0.1) = 0;
/** \details
Returns the overriding rule for the specular highlighting
\param dMaxSpecularFactor [out] Maximal specular highlighting factor
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns A flag that indicates type of the specular highlighting overrride.
\remarks
If flag value is kNone, only own material specular value will be used.
If flag value is kOverride, the incoming value will be used.
If flag value is kUseVisualStyleSpecular, the rule will be the next:
Final specular parameter should be in the range [1;128]. The maximal specular factor (dMaxSpecularFactor)
allows to vary this range. When the maximal specular factor is equal to 1, the final specular parameter will be in the range of [1;128]
(for the value in Visual style equal to 0% the final specular parameter will 128, for the value in Visual style equal to 100% the final specular parameter will 1).
When the maximal specular factor is equal to 0.5, the final specular parameter will be in the range of [1;64]
(for the value in Visual style equal to 0% the final specular parameter will 64, for the value in Visual style equal to 100% the final specular parameter will 1). And so on.
*/
virtual VisualStyleSpecular getUseVisualStyleSpecular(double* dMaxSpecularFactor = NULL, OdTvResult* rc = NULL) const = 0;
/** \details
Sets the normalMap component of this Material object.
\param normalMap [in] Normal map.
\param method [in] Normal map method.
\param strength [in] Normal map strength factor.
\returns A value of type that contains the result of the operation.
\remarks
If the operation was successfully performed, the method returns tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setNormalMap(const OdTvMaterialMap& normalMap, NormalMapMethod method, double strength) = 0;
/** \details
Returns the normalMap component of this Material object.
\param normalMap [out] Receives the normalMap.
\param method [out] Receives normal map method.
\param strength [out] Receives normal map strength factor.
\returns A value of type that contains the result of the operation.
\remarks
If the operation was successfully performed, the method returns tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult getNormalMap(OdTvMaterialMap& normalMap, NormalMapMethod& method, double& strength) const = 0;
/** \details
Sets the cutouts component of this MaterialTraits object.
\param cutoutsMap [in] Cutouts map.
\returns A value of type that contains the result of the operation.
\remarks
If the operation was successfully performed, the method returns tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setCutouts(const OdTvMaterialMap& cutoutsMap) = 0;
/** \details
Returns the cutouts component of this MaterialTraits object.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns A material map object, which appropriates to cutouts.
*/
virtual OdTvMaterialMap getCutouts(OdTvResult* rc = NULL) const = 0;
/** \details
Sets the reflection component of this material object.
\param reflectionMap [in] Reflection map.
\returns A value of type that contains the result of the operation.
\remarks
If the new reflectivity was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
The reflection component creates a mirror finish on the entity.
*/
virtual OdTvResult setReflectionMap(const OdTvMaterialMap& reflectionMap) = 0;
/** \details
Returns the reflection component of this material object.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns Reflection map of this material object.
\remarks
The reflection component creates a mirror finish on the entity.
*/
virtual OdTvMaterialMap getReflectionMap(OdTvResult* rc = NULL) const = 0;
/** \details
Sets the refraction component of this material object.
\param refractionIndex [in] Refraction index.
\param refractionMap [in] Refraction map.
\returns A value of type that contains the result of the operation.
*/
virtual OdTvResult setRefraction(double refractionIndex, const OdTvMaterialMap& refractionMap) = 0;
/** \details
Returns the refraction component of this material object.
\param refractionIndex [out] Receives the refraction index.
\param refractionMap [out] Receives the refraction map.
\returns A value of type that contains the result of the operation.
*/
virtual OdTvResult getRefraction(double& refractionIndex, OdTvMaterialMap& refractionMap) const = 0;
/** \details
Sets the two-sided mode of this material object.
\param bEnable [in] Two-sided mode flag.
\returns A value of type that contains the result of the operation.
*/
virtual OdTvResult setTwoSided(bool bEnable) = 0;
/** \details
Returns the two-sided mode of this material object.
\param rc [out] A pointer to a value of type that contains the result of the retrieve operation.
\returns the two-sided mode of this material object.
*/
virtual bool getTwoSided(OdTvResult* rc = NULL) const = 0;
/** \details
Sets the roughness component of this material object.
\param roughnessMap [in] Roughness map.
\param strength [in] Roughness effect strength.
\returns A value of type that contains the result of the operation.
*/
virtual OdTvResult setRoughness(const OdTvMaterialMap& roughnessMap, double strength) = 0;
/** \details
Returns the roughness component of this material object.
\param roughnessMap [out] Receives the roughness map.
\param strength [out] Receives roughness effect strength.
\returns A value of type that contains the result of the operation.
*/
virtual OdTvResult getRoughness(OdTvMaterialMap& roughnessMap, double& strength) const = 0;
/** \details
Copies all material's data to a specified material.
All current data in the target material will be deleted or overwritten.
\param targetMaterialId [in] A target . The data will be copied to the material the identifier refers.
\param pResolver [in] A smart pointer to the instance of OdTvAttributeResolver.
\returns A value of type that contains the result of the operation.
\remarks
If the operation was successfully performed, the method returns tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult copyTo(OdTvMaterialId& targetMaterialId, OdTvAttributeResolverPtr pResolver) const = 0;
};
/** \details
A data type that represents a smart pointer to an object.
*/
typedef OdTvSmartPtr OdTvMaterialPtr;
/** \details
The interface class for a material object identifier that allows access to the object.
*/
class ODTV_EXPORT OdTvMaterialId : public OdTvId
{
public:
/** \details
Opens the material determined with its identifier for a read or write operation.
\param mode [in] An open mode value.
\param rc [out] A pointer to a value of type that contains the result of the open operation.
\returns A smart pointer to the material object.
\remarks
If the rc parameter is not null and the material object was successfully opened, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
*/
OdTvMaterialPtr openObject(OdTv::OpenMode mode = OdTv::kForRead, OdTvResult* rc = NULL) const;
};
/** \details
The base interface class for the iterator of Visualize SDK material objects.
An iterator object provides sequential access to a collection of materials.
*/
class ODTV_EXPORT OdTvMaterialsIterator : public OdTvIterator, public OdTvIObject
{
public:
/** \details
Retrieves the material object that is currently referenced by the iterator object.
\param rc [out] A pointer to a value of type that contains the result of the operation.
\returns The material object identifier if the iterator refers to a material object; otherwise it returns an identifier with a null value.
\remarks
If the rc parameter is not null and the material object identifier is successfully returned, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the iterator refers to a material object, the identifier that the method returns is not null (i.e., the result of the isNull() method of the identifier is equal to false).
*/
virtual OdTvMaterialId getMaterial(OdTvResult* rc = NULL) const = 0;
/** \details
Searches for the material defined through its identifier and moves the iterator to this material if found.
\param materialId [in] A material identifier.
\returns A value of type that contains the result of the operation.
\remarks
If the material object specified through its identifier is found, the method returns the tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult seek(const OdTvMaterialId& materialId) = 0;
};
/** \details
A data type that represents a smart pointer to an object.
*/
typedef OdTvSmartPtr OdTvMaterialsIteratorPtr;
/** \details
Describes interface for materials comparison.
*/
class ODTV_EXPORT OdTvMaterialComparator
{
public:
/** \details
Compares materials.
\param pMaterial [in] Pointer to the material to compare.
\returns
Returns true if materials are equal; otherwise returns false.
*/
virtual bool isEqual( OdTvMaterialPtr pMaterial ) const = 0;
};
#endif // _ODTV_MATERIAL_H_INCLUDED_