X-Git-Url: http://git.dev.opencascade.org/gitweb/?p=occt.git;a=blobdiff_plain;f=dox%2Fdev_guides%2Fupgrade%2Fupgrade.md;h=09bc12a249a3f5a7a59d29db7c2e4ff05fd6a88a;hb=611684187de2a7b7c59c33f7da9ca51afa64a326;hpb=c8428cb3e456e42cbe875baf6a2b39be41fe0ff3

diff --git a/dox/dev_guides/upgrade/upgrade.md b/dox/dev_guides/upgrade/upgrade.md
index 191c665680..09bc12a249 100644
--- a/dox/dev_guides/upgrade/upgrade.md
+++ b/dox/dev_guides/upgrade/upgrade.md
@@ -1716,6 +1716,40 @@ aGroup->SetPrimitivesAspect (myDrawer->LineAspect()->Aspect()); //!< next array
 aGroup->AddPrimitiveArray (aLines);
 ~~~~
 
+@subsection upgrade_740_materials Material definition
+
+Decomposition of Ambient, Diffuse, Specular and Emissive properties has been eliminated within *Graphic3d_MaterialAspect* definition.
+As result, the following methods of *Graphic3d_MaterialAspect* class have been removed: SetReflectionMode(), SetReflectionModeOn(), Ambient(), Diffuse(), Emissive(), Specular(), SetAmbient(), SetDiffuse(), SetSpecular(), SetEmissive().
+
+Previously, computation of final value required the following code:
+~~~~
+Graphic3d_MaterialAspect theMaterial; Quantity_Color theInteriorColor;
+Graphic3d_Vec3 anAmbient (0.0f);
+if (theMaterial.ReflectionMode (Graphic3d_TOR_AMBIENT))
+{
+  anAmbient = theMaterial.MaterialType (Graphic3d_MATERIAL_ASPECT)
+            ? (Graphic3d_Vec3 )theInteriorColor           * theMaterial.Ambient()
+            : (Graphic3d_Vec3 )theMaterial.AmbientColor() * theMaterial.Ambient();
+}
+~~~~
+
+New code looks like this:
+~~~~
+Graphic3d_MaterialAspect theMaterial; Quantity_Color theInteriorColor;
+Graphic3d_Vec3 anAmbient = theMaterial.AmbientColor();
+if (theMaterial.MaterialType (Graphic3d_MATERIAL_ASPECT)) { anAmbient *= (Graphic3d_Vec3 )theInteriorColor; }
+~~~~
+
+Existing code should be updated to:
+- Replace Graphic3d_MaterialAspect::SetReflectionModeOff() with setting black color; SetReflectionModeOn() calls can be simply removed.
+  R.g. theMaterial.SetAmbientColor(Quantity_NOC_BLACK).
+- Replace Graphic3d_MaterialAspect::Ambient(), SetAmbient(), Diffuse(), SetDiffuse(), Specular(), SetSpecular(), Emissive(), SetEmissive() with methods working with pre-multiplied color.
+  E.g. theMaterial.SetAmbientColor(Graphic3d_Vec3 (1.0f, 0.0f, 0.0f) * 0.2f).
+- Avoid using Graphic3d_MaterialAspect::Color() and SetColor() with non-physical materials (Graphic3d_MATERIAL_ASPECT).
+  These materials do not include color definition, because it is taken from Graphic3d_Aspects::InteriorColor() - this has not been changed.
+  However, previously it was possible storing the color with SetColor() call and then fetching it with Color() by application code (the rendering ignored this value);
+  now SetColor() explicitly ignores call for Graphic3d_MATERIAL_ASPECT materials and Color() returns DiffuseColor() multiplication coefficients.
+
 @subsection upgrade_740_text Changes in Graphic3d_Text and OpenGl_Text API
 
 Parameters of *Text* in *Graphic3d_Group* are moved into a new *Graphic3d_Text* class. *AddText* of *Graphic3d_Group* should be used instead of the previous *Text*.