1 // Copyright (c) 2019 OPEN CASCADE SAS
3 // This file is part of Open CASCADE Technology software library.
5 // This library is free software; you can redistribute it and/or modify it under
6 // the terms of the GNU Lesser General Public License version 2.1 as published
7 // by the Free Software Foundation, with special exception defined in the file
8 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
9 // distribution for complete text of the license and disclaimer of any warranty.
11 // Alternatively, this file may be used under the terms of Open CASCADE
12 // commercial license or contractual agreement.
14 #ifndef _Graphic3d_Aspects_HeaderFile
15 #define _Graphic3d_Aspects_HeaderFile
17 #include <Aspect_PolygonOffsetMode.hxx>
18 #include <Aspect_InteriorStyle.hxx>
19 #include <Aspect_TypeOfDisplayText.hxx>
20 #include <Aspect_TypeOfLine.hxx>
21 #include <Aspect_TypeOfMarker.hxx>
22 #include <Aspect_TypeOfStyleText.hxx>
23 #include <Font_FontAspect.hxx>
24 #include <Font_NameOfFont.hxx>
25 #include <Graphic3d_AlphaMode.hxx>
26 #include <Graphic3d_MarkerImage.hxx>
27 #include <Graphic3d_HatchStyle.hxx>
28 #include <Graphic3d_MaterialAspect.hxx>
29 #include <Graphic3d_PolygonOffset.hxx>
30 #include <Graphic3d_ShaderProgram.hxx>
31 #include <Graphic3d_TextureMap.hxx>
32 #include <Graphic3d_TextureSet.hxx>
33 #include <Graphic3d_TypeOfShadingModel.hxx>
34 #include <TCollection_HAsciiString.hxx>
36 //! This class defines graphic attributes.
37 class Graphic3d_Aspects : public Standard_Transient
39 DEFINE_STANDARD_RTTIEXT(Graphic3d_Aspects, Standard_Transient)
42 //! Creates a context table for drawing primitives defined with the following default values:
43 Standard_EXPORT Graphic3d_Aspects();
45 //! Return interior rendering style; Aspect_IS_SOLID by default.
46 Aspect_InteriorStyle InteriorStyle() const { return myInteriorStyle; }
48 //! Modifies the interior type used for rendering
49 void SetInteriorStyle (const Aspect_InteriorStyle theStyle) { myInteriorStyle = theStyle; }
51 //! Returns shading model; Graphic3d_TOSM_DEFAULT by default.
52 //! Graphic3d_TOSM_DEFAULT means that Shading Model set as default for entire Viewer will be used.
53 Graphic3d_TypeOfShadingModel ShadingModel() const { return myShadingModel; }
55 //! Sets shading model
56 void SetShadingModel (const Graphic3d_TypeOfShadingModel theShadingModel) { myShadingModel = theShadingModel; }
58 //! Returns the way how alpha value should be treated (Graphic3d_AlphaMode_BlendAuto by default, for backward compatibility).
59 Graphic3d_AlphaMode AlphaMode() const { return myAlphaMode; }
61 //! Returns alpha cutoff threshold, for discarding fragments within Graphic3d_AlphaMode_Mask mode (0.5 by default).
62 //! If the alpha value is greater than or equal to this value then it is rendered as fully opaque, otherwise, it is rendered as fully transparent.
63 Standard_ShortReal AlphaCutoff() const { return myAlphaCutoff; }
65 //! Defines the way how alpha value should be treated.
66 void SetAlphaMode (Graphic3d_AlphaMode theMode, Standard_ShortReal theAlphaCutoff = 0.5f)
68 myAlphaMode = theMode;
69 myAlphaCutoff = theAlphaCutoff;
73 const Quantity_ColorRGBA& ColorRGBA() const { return myInteriorColor; }
76 const Quantity_Color& Color() const { return myInteriorColor.GetRGB(); }
78 //! Modifies the color.
79 void SetColor (const Quantity_Color& theColor) { myInteriorColor.SetRGB(theColor); }
81 //! Return interior color.
82 const Quantity_Color& InteriorColor() const { return myInteriorColor.GetRGB(); }
84 //! Return interior color.
85 const Quantity_ColorRGBA& InteriorColorRGBA() const { return myInteriorColor; }
87 //! Modifies the color of the interior of the face
88 void SetInteriorColor (const Quantity_Color& theColor) { myInteriorColor.SetRGB (theColor); }
90 //! Modifies the color of the interior of the face
91 void SetInteriorColor (const Quantity_ColorRGBA& theColor) { myInteriorColor = theColor; }
93 //! Return back interior color.
94 const Quantity_Color& BackInteriorColor() const { return myBackInteriorColor.GetRGB(); }
96 //! Return back interior color.
97 const Quantity_ColorRGBA& BackInteriorColorRGBA() const { return myBackInteriorColor; }
99 //! Modifies the color of the interior of the back face
100 void SetBackInteriorColor (const Quantity_Color& theColor) { myBackInteriorColor.SetRGB (theColor); }
102 //! Modifies the color of the interior of the back face
103 void SetBackInteriorColor (const Quantity_ColorRGBA& theColor) { myBackInteriorColor = theColor; }
105 //! Returns the surface material of external faces
106 const Graphic3d_MaterialAspect& FrontMaterial() const { return myFrontMaterial; }
108 //! Returns the surface material of external faces
109 Graphic3d_MaterialAspect& ChangeFrontMaterial() { return myFrontMaterial; }
111 //! Modifies the surface material of external faces
112 void SetFrontMaterial (const Graphic3d_MaterialAspect& theMaterial) { myFrontMaterial = theMaterial; }
114 //! Returns the surface material of internal faces
115 const Graphic3d_MaterialAspect& BackMaterial() const { return myBackMaterial; }
117 //! Returns the surface material of internal faces
118 Graphic3d_MaterialAspect& ChangeBackMaterial() { return myBackMaterial; }
120 //! Modifies the surface material of internal faces
121 void SetBackMaterial (const Graphic3d_MaterialAspect& theMaterial) { myBackMaterial = theMaterial; }
123 //! Returns true if back faces should be suppressed (true by default).
124 bool ToSuppressBackFaces() const { return myToSuppressBackFaces; }
126 //! Assign back faces culling flag.
127 void SetSuppressBackFaces (bool theToSuppress) { myToSuppressBackFaces = theToSuppress; }
129 //! Returns true if back faces should be suppressed (true by default).
130 bool BackFace() const { return myToSuppressBackFaces; }
132 //! Allows the display of back-facing filled polygons.
133 void AllowBackFace() { myToSuppressBackFaces = false; }
135 //! Suppress the display of back-facing filled polygons.
136 //! A back-facing polygon is defined as a polygon whose
137 //! vertices are in a clockwise order with respect to screen coordinates.
138 void SuppressBackFace() { myToSuppressBackFaces = true; }
140 //! Returns true if material properties should be distinguished for back and front faces (false by default).
141 bool Distinguish() const { return myToDistinguishMaterials; }
143 //! Set material distinction between front and back faces.
144 void SetDistinguish (bool toDistinguish) { myToDistinguishMaterials = toDistinguish; }
146 //! Allows material distinction between front and back faces.
147 void SetDistinguishOn() { myToDistinguishMaterials = true; }
149 //! Forbids material distinction between front and back faces.
150 void SetDistinguishOff() { myToDistinguishMaterials = false; }
152 //! Return shader program.
153 const Handle(Graphic3d_ShaderProgram)& ShaderProgram() const { return myProgram; }
155 //! Sets up OpenGL/GLSL shader program.
156 void SetShaderProgram (const Handle(Graphic3d_ShaderProgram)& theProgram) { myProgram = theProgram; }
158 //! Return texture array to be mapped.
159 const Handle(Graphic3d_TextureSet)& TextureSet() const { return myTextureSet; }
161 //! Setup texture array to be mapped.
162 void SetTextureSet (const Handle(Graphic3d_TextureSet)& theTextures) { myTextureSet = theTextures; }
164 //! Return texture to be mapped.
165 //Standard_DEPRECATED("Deprecated method, TextureSet() should be used instead")
166 Handle(Graphic3d_TextureMap) TextureMap() const
168 return !myTextureSet.IsNull() && !myTextureSet->IsEmpty()
169 ? myTextureSet->First()
170 : Handle(Graphic3d_TextureMap)();
173 //! Assign texture to be mapped.
174 //! See also SetTextureMapOn() to actually activate texture mapping.
175 //Standard_DEPRECATED("Deprecated method, SetTextureSet() should be used instead")
176 Standard_EXPORT void SetTextureMap (const Handle(Graphic3d_TextureMap)& theTexture);
178 //! Return true if texture mapping is enabled (false by default).
179 bool ToMapTexture() const { return myToMapTexture; }
181 //! Return true if texture mapping is enabled (false by default).
182 bool TextureMapState() const { return myToMapTexture; }
184 //! Enable or disable texture mapping (has no effect if texture is not set).
185 void SetTextureMapOn (bool theToMap) { myToMapTexture = theToMap; }
187 //! Enable texture mapping (has no effect if texture is not set).
188 void SetTextureMapOn() { myToMapTexture = true; }
190 //! Disable texture mapping.
191 void SetTextureMapOff() { myToMapTexture = false; }
193 //! Returns current polygon offsets settings.
194 const Graphic3d_PolygonOffset& PolygonOffset() const { return myPolygonOffset; }
196 //! Sets polygon offsets settings.
197 void SetPolygonOffset (const Graphic3d_PolygonOffset& theOffset) { myPolygonOffset = theOffset; }
199 //! Returns current polygon offsets settings.
200 void PolygonOffsets (Standard_Integer& theMode,
201 Standard_ShortReal& theFactor,
202 Standard_ShortReal& theUnits) const
204 theMode = myPolygonOffset.Mode;
205 theFactor = myPolygonOffset.Factor;
206 theUnits = myPolygonOffset.Units;
209 //! Sets up OpenGL polygon offsets mechanism.
210 //! <aMode> parameter can contain various combinations of
211 //! Aspect_PolygonOffsetMode enumeration elements (Aspect_POM_None means
212 //! that polygon offsets are not changed).
213 //! If <aMode> is different from Aspect_POM_Off and Aspect_POM_None, then <aFactor> and <aUnits>
214 //! arguments are used by graphic renderer to calculate a depth offset value:
216 //! offset = <aFactor> * m + <aUnits> * r, where
217 //! m - maximum depth slope for the polygon currently being displayed,
218 //! r - minimum window coordinates depth resolution (implementation-specific)
220 //! Default settings for OCC 3D viewer: mode = Aspect_POM_Fill, factor = 1., units = 0.
222 //! Negative offset values move polygons closer to the viewport,
223 //! while positive values shift polygons away.
224 //! Consult OpenGL reference for details (glPolygonOffset function description).
225 void SetPolygonOffsets (const Standard_Integer theMode,
226 const Standard_ShortReal theFactor = 1.0f,
227 const Standard_ShortReal theUnits = 0.0f)
229 myPolygonOffset.Mode = (Aspect_PolygonOffsetMode )(theMode & Aspect_POM_Mask);
230 myPolygonOffset.Factor = theFactor;
231 myPolygonOffset.Units = theUnits;
234 //! @name parameters specific to Line primitive rendering
237 //! Return line type; Aspect_TOL_SOLID by default.
238 Aspect_TypeOfLine LineType() const { return myLineType; }
240 //! Modifies the line type
241 void SetLineType (Aspect_TypeOfLine theType) { myLineType = theType; }
243 //! Return width for edges in pixels; 1.0 by default.
244 Standard_ShortReal LineWidth() const { return myLineWidth; }
246 //! Modifies the line thickness
247 //! Warning: Raises Standard_OutOfRange if the width is a negative value.
248 void SetLineWidth (Standard_ShortReal theWidth)
250 if (theWidth <= 0.0f)
252 throw Standard_OutOfRange ("Bad value for EdgeLineWidth");
254 myLineWidth = theWidth;
257 //! @name parameters specific to Point (Marker) primitive rendering
260 //! Return marker type; Aspect_TOM_POINT by default.
261 Aspect_TypeOfMarker MarkerType() const { return myMarkerType; }
263 //! Modifies the type of marker.
264 void SetMarkerType (Aspect_TypeOfMarker theType) { myMarkerType = theType; }
266 //! Return marker scale factor; 1.0 by default.
267 Standard_ShortReal MarkerScale() const { return myMarkerScale; }
269 //! Modifies the scale factor.
270 //! Marker type Aspect_TOM_POINT is not affected by the marker size scale factor.
271 //! It is always the smallest displayable dot.
272 //! Warning: Raises Standard_OutOfRange if the scale is a negative value.
273 void SetMarkerScale (const Standard_ShortReal theScale)
275 if (theScale <= 0.0f)
277 throw Standard_OutOfRange ("Bad value for MarkerScale");
279 myMarkerScale = theScale;
282 //! Returns marker's image texture.
283 //! Could be null handle if marker aspect has been initialized as default type of marker.
284 const Handle(Graphic3d_MarkerImage)& MarkerImage() const { return myMarkerImage; }
286 //! Set marker's image texture.
287 void SetMarkerImage (const Handle(Graphic3d_MarkerImage)& theImage) { myMarkerImage = theImage; }
289 //! Returns TRUE if marker should be drawn using marker sprite (either user-provided or generated).
290 bool IsMarkerSprite() const
292 if (myMarkerType == Aspect_TOM_POINT
293 || myMarkerType == Aspect_TOM_EMPTY)
298 return myMarkerType != Aspect_TOM_USERDEFINED
299 || !myMarkerImage.IsNull();
302 //! @name parameters specific to text rendering
305 //! Returns the font; NULL string by default.
306 const Handle(TCollection_HAsciiString)& TextFont() const { return myTextFont; }
308 //! Modifies the font.
309 void SetTextFont (const Handle(TCollection_HAsciiString)& theFont) { myTextFont = theFont; }
311 //! Returns text FontAspect
312 Font_FontAspect TextFontAspect() const { return myTextFontAspect; }
314 //! Turns usage of Aspect text
315 void SetTextFontAspect (Font_FontAspect theFontAspect) { myTextFontAspect = theFontAspect; }
317 //! Returns display type; Aspect_TODT_NORMAL by default.
318 Aspect_TypeOfDisplayText TextDisplayType() const { return myTextDisplayType; }
320 //! Sets display type.
321 void SetTextDisplayType (Aspect_TypeOfDisplayText theType) { myTextDisplayType = theType; }
323 //! Returns text background/shadow color; equals to EdgeColor() property.
324 const Quantity_ColorRGBA& ColorSubTitleRGBA() const { return myEdgeColor; }
326 //! Return text background/shadow color; equals to EdgeColor() property.
327 const Quantity_Color& ColorSubTitle() const { return myEdgeColor.GetRGB(); }
329 //! Modifies text background/shadow color; equals to EdgeColor() property.
330 void SetColorSubTitle (const Quantity_Color& theColor) { myEdgeColor.SetRGB (theColor); }
332 //! Modifies text background/shadow color; equals to EdgeColor() property.
333 void SetColorSubTitle (const Quantity_ColorRGBA& theColor) { myEdgeColor = theColor; }
335 //! Returns TRUE when the Text Zoomable is on.
336 bool IsTextZoomable() const { return myIsTextZoomable; }
338 //! Turns usage of text zoomable on/off
339 void SetTextZoomable (bool theFlag) { myIsTextZoomable = theFlag; }
341 //! Returns the text style; Aspect_TOST_NORMAL by default.
342 Aspect_TypeOfStyleText TextStyle() const { return myTextStyle; }
344 //! Modifies the style of the text.
345 void SetTextStyle (Aspect_TypeOfStyleText theStyle) { myTextStyle = theStyle; }
347 //! Returns Angle of degree
348 Standard_ShortReal TextAngle() const { return myTextAngle; }
350 //! Turns usage of text rotated
351 void SetTextAngle (Standard_ShortReal theAngle) { myTextAngle = (Standard_ShortReal )theAngle; }
353 //! @name parameters specific to Mesh Edges (of triangulation primitive) rendering
356 //! Returns true if mesh edges should be drawn (false by default).
357 bool ToDrawEdges() const { return myToDrawEdges && myLineType != Aspect_TOL_EMPTY; }
359 //! Set if mesh edges should be drawn or not.
360 void SetDrawEdges (bool theToDraw)
362 myToDrawEdges = theToDraw;
363 if (myLineType == Aspect_TOL_EMPTY)
365 myLineType = Aspect_TOL_SOLID;
369 //! The edges of FillAreas are drawn.
370 void SetEdgeOn() { SetDrawEdges (true); }
372 //! The edges of FillAreas are not drawn.
373 void SetEdgeOff() { SetDrawEdges (false); }
375 //! Return color of edges.
376 const Quantity_Color& EdgeColor() const { return myEdgeColor.GetRGB(); }
378 //! Return color of edges.
379 const Quantity_ColorRGBA& EdgeColorRGBA() const { return myEdgeColor; }
381 //! Modifies the color of the edge of the face
382 void SetEdgeColor (const Quantity_Color& theColor) { myEdgeColor.SetRGB (theColor); }
384 //! Modifies the color of the edge of the face
385 void SetEdgeColor (const Quantity_ColorRGBA& theColor) { myEdgeColor = theColor; }
387 //! Return edges line type (same as LineType()).
388 Aspect_TypeOfLine EdgeLineType() const { return myLineType; }
390 //! Modifies the edge line type (same as SetLineType())
391 void SetEdgeLineType (Aspect_TypeOfLine theType) { myLineType = theType; }
393 //! Return width for edges in pixels (same as LineWidth()).
394 Standard_ShortReal EdgeWidth() const { return myLineWidth; }
396 //! Modifies the edge thickness (same as SetLineWidth())
397 void SetEdgeWidth (Standard_Real theWidth) { SetLineWidth ((Standard_ShortReal )theWidth); }
399 //! Returns TRUE if drawing element edges should discard first edge in triangle; FALSE by default.
400 //! Graphics hardware works mostly with triangles, so that wireframe presentation will draw triangle edges by default.
401 //! This flag allows rendering wireframe presentation of quad-only array split into triangles.
402 //! For this, quads should be split in specific order, so that the quad diagonal (to be NOT rendered) goes first:
404 //! / / Triangle #1: 2-0-1; Triangle #2: 0-2-3
406 bool ToSkipFirstEdge() const { return myToSkipFirstEdge; }
408 //! Set skip first triangle edge flag for drawing wireframe presentation of quads array split into triangles.
409 void SetSkipFirstEdge (bool theToSkipFirstEdge) { myToSkipFirstEdge = theToSkipFirstEdge; }
411 //! Returns TRUE if silhouette (outline) should be drawn (with edge color and width); FALSE by default.
412 bool ToDrawSilhouette() const { return myToDrawSilhouette; }
414 //! Enables/disables drawing silhouette (outline).
415 void SetDrawSilhouette (bool theToDraw) { myToDrawSilhouette = theToDraw; }
419 //! Returns the hatch type used when InteriorStyle is IS_HATCH
420 const Handle(Graphic3d_HatchStyle)& HatchStyle() const { return myHatchStyle; }
422 //! Modifies the hatch type used when InteriorStyle is IS_HATCH
423 void SetHatchStyle (const Handle(Graphic3d_HatchStyle)& theStyle) { myHatchStyle = theStyle; }
425 //! Modifies the hatch type used when InteriorStyle is IS_HATCH
426 //! @warning This method always creates a new handle for a given hatch style
427 void SetHatchStyle (const Aspect_HatchStyle theStyle)
429 if (theStyle == Aspect_HS_SOLID)
431 myHatchStyle.Nullify();
435 myHatchStyle = new Graphic3d_HatchStyle (theStyle);
440 //! Check for equality with another aspects.
441 bool IsEqual (const Graphic3d_Aspects& theOther)
443 if (this == &theOther)
448 return myProgram == theOther.myProgram
449 && myTextureSet == theOther.myTextureSet
450 && myMarkerImage == theOther.myMarkerImage
451 && myInteriorColor == theOther.myInteriorColor
452 && myBackInteriorColor == theOther.myBackInteriorColor
453 && myFrontMaterial == theOther.myFrontMaterial
454 && myBackMaterial == theOther.myBackMaterial
455 && myInteriorStyle == theOther.myInteriorStyle
456 && myShadingModel == theOther.myShadingModel
457 && myAlphaMode == theOther.myAlphaMode
458 && myAlphaCutoff == theOther.myAlphaCutoff
459 && myLineType == theOther.myLineType
460 && myEdgeColor == theOther.myEdgeColor
461 && myLineWidth == theOther.myLineWidth
462 && myMarkerType == theOther.myMarkerType
463 && myMarkerScale == theOther.myMarkerScale
464 && myHatchStyle == theOther.myHatchStyle
465 && myTextFont == theOther.myTextFont
466 && myPolygonOffset == theOther.myPolygonOffset
467 && myTextStyle == theOther.myTextStyle
468 && myTextDisplayType == theOther.myTextDisplayType
469 && myTextFontAspect == theOther.myTextFontAspect
470 && myTextAngle == theOther.myTextAngle
471 && myToSkipFirstEdge == theOther.myToSkipFirstEdge
472 && myToDistinguishMaterials == theOther.myToDistinguishMaterials
473 && myToDrawEdges == theOther.myToDrawEdges
474 && myToDrawSilhouette == theOther.myToDrawSilhouette
475 && myToSuppressBackFaces == theOther.myToSuppressBackFaces
476 && myToMapTexture == theOther.myToMapTexture
477 && myIsTextZoomable == theOther.myIsTextZoomable;
480 //! Dumps the content of me into the stream
481 Standard_EXPORT void DumpJson (Standard_OStream& theOStream, const Standard_Integer theDepth = -1) const;
485 Handle(Graphic3d_ShaderProgram) myProgram;
486 Handle(Graphic3d_TextureSet) myTextureSet;
487 Handle(Graphic3d_MarkerImage) myMarkerImage;
488 Handle(Graphic3d_HatchStyle) myHatchStyle;
489 Handle(TCollection_HAsciiString) myTextFont;
490 Graphic3d_MaterialAspect myFrontMaterial;
491 Graphic3d_MaterialAspect myBackMaterial;
493 Quantity_ColorRGBA myInteriorColor;
494 Quantity_ColorRGBA myBackInteriorColor;
495 Quantity_ColorRGBA myEdgeColor;
497 Graphic3d_PolygonOffset myPolygonOffset;
498 Aspect_InteriorStyle myInteriorStyle;
499 Graphic3d_TypeOfShadingModel myShadingModel;
500 Graphic3d_AlphaMode myAlphaMode;
501 Standard_ShortReal myAlphaCutoff;
503 Aspect_TypeOfLine myLineType;
504 Standard_ShortReal myLineWidth;
506 Aspect_TypeOfMarker myMarkerType;
507 Standard_ShortReal myMarkerScale;
509 Aspect_TypeOfStyleText myTextStyle;
510 Aspect_TypeOfDisplayText myTextDisplayType;
511 Font_FontAspect myTextFontAspect;
512 Standard_ShortReal myTextAngle;
514 bool myToSkipFirstEdge;
515 bool myToDistinguishMaterials;
517 bool myToDrawSilhouette;
518 bool myToSuppressBackFaces;
520 bool myIsTextZoomable;
524 DEFINE_STANDARD_HANDLE(Graphic3d_Aspects, Standard_Transient)
526 #endif // _Graphic3d_Aspects_HeaderFile