src/Graphic3d/Graphic3d_RenderingParams.hxx

   1 // Created on: 2014-05-14
   2 // Created by: Denis BOGOLEPOV
   3 // Copyright (c) 2014 OPEN CASCADE SAS
   4 //
   5 // This file is part of Open CASCADE Technology software library.
   6 //
   7 // This library is free software; you can redistribute it and/or modify it under
   8 // the terms of the GNU Lesser General Public License version 2.1 as published
   9 // by the Free Software Foundation, with special exception defined in the file
  10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 // distribution for complete text of the license and disclaimer of any warranty.
  12 //
  13 // Alternatively, this file may be used under the terms of Open CASCADE
  14 // commercial license or contractual agreement.
  15
  16 #ifndef _Graphic3d_RenderingParams_HeaderFile
  17 #define _Graphic3d_RenderingParams_HeaderFile
  18
  19 #include <Font_Hinting.hxx>
  20 #include <Graphic3d_AspectText3d.hxx>
  21 #include <Graphic3d_TransformPers.hxx>
  22 #include <Graphic3d_RenderTransparentMethod.hxx>
  23 #include <Graphic3d_RenderingMode.hxx>
  24 #include <Graphic3d_StereoMode.hxx>
  25 #include <Graphic3d_ToneMappingMethod.hxx>
  26 #include <Graphic3d_TypeOfShadingModel.hxx>
  27 #include <Graphic3d_Vec4.hxx>
  28
  29 //! Helper class to store rendering parameters.
  30 class Graphic3d_RenderingParams
  31 {
  32 public:
  33   //! Default pixels density.
  34   static const unsigned int THE_DEFAULT_RESOLUTION = 72u;
  35
  36   //! Default ray-tracing depth.
  37   static const Standard_Integer THE_DEFAULT_DEPTH = 3;
  38
  39   //! Anaglyph filter presets.
  40   enum Anaglyph
  41   {
  42     Anaglyph_RedCyan_Simple,       //!< simple    filter for Red-Cyan      glasses (R+GB)
  43     Anaglyph_RedCyan_Optimized,    //!< optimized filter for Red-Cyan      glasses (R+GB)
  44     Anaglyph_YellowBlue_Simple,    //!< simple    filter for Yellow-Blue   glasses (RG+B)
  45     Anaglyph_YellowBlue_Optimized, //!< optimized filter for Yellow-Blue   glasses (RG+B)
  46     Anaglyph_GreenMagenta_Simple,  //!< simple    filter for Green-Magenta glasses (G+RB)
  47     Anaglyph_UserDefined           //!< use externally specified matrices
  48   };
  49
  50   //! Statistics display flags.
  51   //! If not specified otherwise, the counter value is computed for a single rendered frame.
  52   enum PerfCounters
  53   {
  54     PerfCounters_NONE        = 0x000, //!< no stats
  55     PerfCounters_FrameRate   = 0x001, //!< Frame Rate,        frames per second (number of frames within elapsed time)
  56     PerfCounters_CPU         = 0x002, //!< CPU utilization as frames per second (number of frames within CPU utilization time (rendering thread))
  57     PerfCounters_Layers      = 0x004, //!< count layers (groups of structures)
  58     PerfCounters_Structures  = 0x008, //!< count low-level Structures (normal unhighlighted Presentable Object is usually represented by 1 Structure)
  59     //
  60     PerfCounters_Groups      = 0x010, //!< count primitive Groups (1 Structure holds 1 or more primitive Group)
  61     PerfCounters_GroupArrays = 0x020, //!< count Arrays within Primitive Groups (optimal primitive Group holds 1 Array)
  62     //
  63     PerfCounters_Triangles   = 0x040, //!< count Triangles
  64     PerfCounters_Points      = 0x080, //!< count Points
  65     PerfCounters_Lines       = 0x100, //!< count Line segments
  66     //
  67     PerfCounters_EstimMem    = 0x200, //!< estimated GPU memory usage
  68     //
  69     PerfCounters_FrameTime   = 0x400, //!< frame CPU utilization time (rendering thread); @sa Graphic3d_FrameStatsTimer
  70     PerfCounters_FrameTimeMax= 0x800, //!< maximum frame times
  71     //
  72     PerfCounters_SkipImmediate = 0x1000, //!< do not include immediate viewer updates (e.g. lazy updates without redrawing entire view content)
  73     //! show basic statistics
  74     PerfCounters_Basic = PerfCounters_FrameRate | PerfCounters_CPU | PerfCounters_Layers | PerfCounters_Structures,
  75     //! extended (verbose) statistics
  76     PerfCounters_Extended = PerfCounters_Basic
  77                           | PerfCounters_Groups | PerfCounters_GroupArrays
  78                           | PerfCounters_Triangles | PerfCounters_Points | PerfCounters_Lines
  79                           | PerfCounters_EstimMem,
  80     //! all counters
  81     PerfCounters_All = PerfCounters_Extended
  82                      | PerfCounters_FrameTime
  83                      | PerfCounters_FrameTimeMax,
  84   };
  85
  86   //! State of frustum culling optimization.
  87   enum FrustumCulling
  88   {
  89     FrustumCulling_Off,     //!< culling is disabled
  90     FrustumCulling_On,      //!< culling is active, and the list of culled entities is automatically updated before redraw
  91     FrustumCulling_NoUpdate //!< culling is active, but the list of culled entities is not updated
  92   };
  93
  94 public:
  95
  96   //! Creates default rendering parameters.
  97   Graphic3d_RenderingParams()
  98   : Method                      (Graphic3d_RM_RASTERIZATION),
  99     ShadingModel                (Graphic3d_TOSM_FRAGMENT),
 100     TransparencyMethod          (Graphic3d_RTM_BLEND_UNORDERED),
 101     Resolution                  (THE_DEFAULT_RESOLUTION),
 102     FontHinting                 (Font_Hinting_Off),
 103     LineFeather                 (1.0f),
 104     // PBR parameters
 105     PbrEnvPow2Size              (9),
 106     PbrEnvSpecMapNbLevels       (6),
 107     PbrEnvBakingDiffNbSamples   (1024),
 108     PbrEnvBakingSpecNbSamples   (256),
 109     PbrEnvBakingProbability     (0.99f),
 110     //
 111     OitDepthFactor              (0.0f),
 112     NbOitDepthPeelingLayers     (4),
 113     NbMsaaSamples               (0),
 114     RenderResolutionScale       (1.0f),
 115     ShadowMapResolution         (1024),
 116     ShadowMapBias               (0.005f),
 117     ToEnableDepthPrepass        (Standard_False),
 118     ToEnableAlphaToCoverage     (Standard_True),
 119     // ray tracing parameters
 120     IsGlobalIlluminationEnabled (Standard_False),
 121     SamplesPerPixel(0),
 122     RaytracingDepth             (THE_DEFAULT_DEPTH),
 123     IsShadowEnabled             (Standard_True),
 124     IsReflectionEnabled         (Standard_False),
 125     IsAntialiasingEnabled       (Standard_False),
 126     IsTransparentShadowEnabled  (Standard_False),
 127     UseEnvironmentMapBackground (Standard_False),
 128     ToIgnoreNormalMapInRayTracing (Standard_False),
 129     CoherentPathTracingMode     (Standard_False),
 130     AdaptiveScreenSampling      (Standard_False),
 131     AdaptiveScreenSamplingAtomic(Standard_False),
 132     ShowSamplingTiles           (Standard_False),
 133     TwoSidedBsdfModels          (Standard_False),
 134     RadianceClampingValue       (30.0),
 135     RebuildRayTracingShaders    (Standard_False),
 136     RayTracingTileSize          (32),
 137     NbRayTracingTiles           (16 * 16),
 138     CameraApertureRadius        (0.0f),
 139     CameraFocalPlaneDist        (1.0f),
 140     FrustumCullingState         (FrustumCulling_On),
 141     ToneMappingMethod           (Graphic3d_ToneMappingMethod_Disabled),
 142     Exposure                    (0.f),
 143     WhitePoint                  (1.f),
 144     // stereoscopic parameters
 145     StereoMode (Graphic3d_StereoMode_QuadBuffer),
 146     HmdFov2d (30.0f),
 147     AnaglyphFilter (Anaglyph_RedCyan_Optimized),
 148     ToReverseStereo (Standard_False),
 149     ToMirrorComposer (Standard_True),
 150     //
 151     StatsPosition (new Graphic3d_TransformPers (Graphic3d_TMF_2d, Aspect_TOTP_LEFT_UPPER,  Graphic3d_Vec2i (20, 20))),
 152     ChartPosition (new Graphic3d_TransformPers (Graphic3d_TMF_2d, Aspect_TOTP_RIGHT_UPPER, Graphic3d_Vec2i (20, 20))),
 153     ChartSize (-1, -1),
 154     StatsTextAspect (new Graphic3d_AspectText3d()),
 155     StatsUpdateInterval (1.0),
 156     StatsTextHeight (16),
 157     StatsNbFrames (1),
 158     StatsMaxChartTime (0.1f),
 159     CollectedStats (PerfCounters_Basic),
 160     ToShowStats (Standard_False)
 161   {
 162     const Graphic3d_Vec4 aZero (0.0f, 0.0f, 0.0f, 0.0f);
 163     AnaglyphLeft .SetRow (0, Graphic3d_Vec4 (1.0f,  0.0f,  0.0f, 0.0f));
 164     AnaglyphLeft .SetRow (1, aZero);
 165     AnaglyphLeft .SetRow (2, aZero);
 166     AnaglyphLeft .SetRow (3, aZero);
 167     AnaglyphRight.SetRow (0, aZero);
 168     AnaglyphRight.SetRow (1, Graphic3d_Vec4 (0.0f,  1.0f,  0.0f, 0.0f));
 169     AnaglyphRight.SetRow (2, Graphic3d_Vec4 (0.0f,  0.0f,  1.0f, 0.0f));
 170     AnaglyphRight.SetRow (3, aZero);
 171
 172     StatsTextAspect->SetColor (Quantity_NOC_WHITE);
 173     StatsTextAspect->SetColorSubTitle (Quantity_NOC_BLACK);
 174     StatsTextAspect->SetFont (Font_NOF_ASCII_MONO);
 175     StatsTextAspect->SetDisplayType (Aspect_TODT_SHADOW);
 176     StatsTextAspect->SetTextZoomable (Standard_False);
 177     StatsTextAspect->SetTextFontAspect (Font_FA_Regular);
 178   }
 179
 180   //! Returns resolution ratio.
 181   Standard_ShortReal ResolutionRatio() const
 182   {
 183     return Resolution / static_cast<Standard_ShortReal> (THE_DEFAULT_RESOLUTION);
 184   }
 185
 186   //! Dumps the content of me into the stream
 187   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
 188
 189 public: //! @name general parameters
 190
 191   Graphic3d_RenderingMode           Method;                      //!< specifies rendering mode, Graphic3d_RM_RASTERIZATION by default
 192   Graphic3d_TypeOfShadingModel      ShadingModel;                //!< specified default shading model, Graphic3d_TOSM_FRAGMENT by default
 193   Graphic3d_RenderTransparentMethod TransparencyMethod;          //!< specifies rendering method for transparent graphics
 194   unsigned int                      Resolution;                  //!< Pixels density (PPI), defines scaling factor for parameters like text size
 195                                                                  //!  (when defined in screen-space units rather than in 3D) to be properly displayed
 196                                                                  //!  on device (screen / printer). 72 is default value.
 197                                                                  //!  Note that using difference resolution in different Views in same Viewer
 198                                                                  //!  will lead to performance regression (for example, text will be recreated every time).
 199   Font_Hinting                      FontHinting;                 //!< enables/disables text hinting within textured fonts, Font_Hinting_Off by default;
 200                                                                  //!  hinting improves readability of thin text on low-resolution screen,
 201                                                                  //!  but adds distortions to original font depending on font family and font library version
 202   Standard_ShortReal                LineFeather;                 //!< line feather width in pixels (> 0.0), 1.0 by default;
 203                                                                  //!  high values produce blurred results, small values produce sharp (aliased) edges
 204
 205 public: //! @name rendering resolution parameters
 206
 207   Standard_Integer                  PbrEnvPow2Size;              //!< size of IBL maps side can be calculated as 2^PbrEnvPow2Size (> 0), 9 by default
 208   Standard_Integer                  PbrEnvSpecMapNbLevels;       //!< number of levels used in specular IBL map (> 1), 6 by default
 209   Standard_Integer                  PbrEnvBakingDiffNbSamples;   //!< number of samples used in Monte-Carlo integration during diffuse IBL map's
 210                                                                  //!  spherical harmonics coefficients generation (> 0), 1024 by default
 211   Standard_Integer                  PbrEnvBakingSpecNbSamples;   //!< number of samples used in Monte-Carlo integration during specular IBL map's generation (> 0), 256 by default
 212   Standard_ShortReal                PbrEnvBakingProbability;     //!< controls strength of samples reducing strategy during specular IBL map's generation
 213                                                                  //!  (see 'SpecIBLMapSamplesFactor' function for detail explanation) [0.0, 1.0], 0.99 by default
 214
 215   Standard_ShortReal                OitDepthFactor;              //!< scalar factor [0-1] controlling influence of depth of a fragment to its final coverage (Graphic3d_RTM_BLEND_OIT), 0.0 by default
 216   Standard_Integer                  NbOitDepthPeelingLayers;     //!< number of depth peeling (Graphic3d_RTM_DEPTH_PEELING_OIT) layers, 4 by default
 217   Standard_Integer                  NbMsaaSamples;               //!< number of MSAA samples (should be within 0..GL_MAX_SAMPLES, power-of-two number), 0 by default
 218   Standard_ShortReal                RenderResolutionScale;       //!< rendering resolution scale factor, 1 by default;
 219                                                                  //!  incompatible with MSAA (e.g. NbMsaaSamples should be set to 0)
 220   Standard_Integer                  ShadowMapResolution;         //!< shadow texture map resolution, 1024 by default
 221   Standard_ShortReal                ShadowMapBias;               //!< shadowmap bias, 0.005 by default;
 222   Standard_Boolean                  ToEnableDepthPrepass;        //!< enables/disables depth pre-pass, False by default
 223   Standard_Boolean                  ToEnableAlphaToCoverage;     //!< enables/disables alpha to coverage, True by default
 224
 225 public: //! @name Ray-Tracing/Path-Tracing parameters
 226
 227   Standard_Boolean                  IsGlobalIlluminationEnabled; //!< enables/disables global illumination effects (path tracing)
 228   Standard_Integer                  SamplesPerPixel;             //!< number of samples per pixel (SPP)
 229   Standard_Integer                  RaytracingDepth;             //!< maximum ray-tracing depth, 3 by default
 230   Standard_Boolean                  IsShadowEnabled;             //!< enables/disables shadows rendering, True by default
 231   Standard_Boolean                  IsReflectionEnabled;         //!< enables/disables specular reflections, False by default
 232   Standard_Boolean                  IsAntialiasingEnabled;       //!< enables/disables adaptive anti-aliasing, False by default
 233   Standard_Boolean                  IsTransparentShadowEnabled;  //!< enables/disables light propagation through transparent media, False by default
 234   Standard_Boolean                  UseEnvironmentMapBackground; //!< enables/disables environment map background
 235   Standard_Boolean                  ToIgnoreNormalMapInRayTracing; //!< enables/disables normal map ignoring during path tracing; FALSE by default
 236   Standard_Boolean                  CoherentPathTracingMode;     //!< enables/disables 'coherent' tracing mode (single RNG seed within 16x16 image blocks)
 237   Standard_Boolean                  AdaptiveScreenSampling;      //!< enables/disables adaptive screen sampling mode for path tracing, FALSE by default
 238   Standard_Boolean                  AdaptiveScreenSamplingAtomic;//!< enables/disables usage of atomic float operations within adaptive screen sampling, FALSE by default
 239   Standard_Boolean                  ShowSamplingTiles;           //!< enables/disables debug mode for adaptive screen sampling, FALSE by default
 240   Standard_Boolean                  TwoSidedBsdfModels;          //!< forces path tracing to use two-sided versions of original one-sided scattering models
 241   Standard_ShortReal                RadianceClampingValue;       //!< maximum radiance value used for clamping radiance estimation.
 242   Standard_Boolean                  RebuildRayTracingShaders;    //!< forces rebuilding ray tracing shaders at the next frame
 243   Standard_Integer                  RayTracingTileSize;          //!< screen tile size, 32 by default (adaptive sampling mode of path tracing);
 244   Standard_Integer                  NbRayTracingTiles;           //!< maximum number of screen tiles per frame, 256 by default (adaptive sampling mode of path tracing);
 245                                                                  //!  this parameter limits the number of tiles to be rendered per redraw, increasing Viewer interactivity,
 246                                                                  //!  but also increasing the time for achieving a good quality; -1 means no limit
 247   Standard_ShortReal                CameraApertureRadius;        //!< aperture radius of perspective camera used for depth-of-field, 0.0 by default (no DOF) (path tracing only)
 248   Standard_ShortReal                CameraFocalPlaneDist;        //!< focal  distance of perspective camera used for depth-of field, 1.0 by default (path tracing only)
 249   FrustumCulling                    FrustumCullingState;         //!< state of frustum culling optimization; FrustumCulling_On by default
 250
 251   Graphic3d_ToneMappingMethod       ToneMappingMethod;           //!< specifies tone mapping method for path tracing, Graphic3d_ToneMappingMethod_Disabled by default
 252   Standard_ShortReal                Exposure;                    //!< exposure value used for tone mapping (path tracing), 0.0 by default
 253   Standard_ShortReal                WhitePoint;                  //!< white point value used in filmic tone mapping (path tracing), 1.0 by default
 254
 255 public: //! @name VR / stereoscopic parameters
 256
 257   Graphic3d_StereoMode              StereoMode;                  //!< stereoscopic output mode, Graphic3d_StereoMode_QuadBuffer by default
 258   Standard_ShortReal                HmdFov2d;                    //!< sharp field of view range in degrees for displaying on-screen 2D elements, 30.0 by default;
 259   Anaglyph                          AnaglyphFilter;              //!< filter for anaglyph output, Anaglyph_RedCyan_Optimized by default
 260   Graphic3d_Mat4                    AnaglyphLeft;                //!< left  anaglyph filter (in normalized colorspace), Color = AnaglyphRight * theColorRight + AnaglyphLeft * theColorLeft;
 261   Graphic3d_Mat4                    AnaglyphRight;               //!< right anaglyph filter (in normalized colorspace), Color = AnaglyphRight * theColorRight + AnaglyphLeft * theColorLeft;
 262   Standard_Boolean                  ToReverseStereo;             //!< flag to reverse stereo pair, FALSE by default
 263   Standard_Boolean                  ToMirrorComposer;            //!< if output device is an external composer - mirror rendering results in window in addition to sending frame to composer, TRUE by default
 264
 265 public: //! @name on-screen display parameters
 266
 267   Handle(Graphic3d_TransformPers)   StatsPosition;               //!< location of stats, upper-left position by default
 268   Handle(Graphic3d_TransformPers)   ChartPosition;               //!< location of stats chart, upper-right position by default
 269   Graphic3d_Vec2i                   ChartSize;                   //!< chart size in pixels, (-1, -1) by default which means that chart will occupy a portion of viewport
 270   Handle(Graphic3d_AspectText3d)    StatsTextAspect;             //!< stats text aspect
 271   Standard_ShortReal                StatsUpdateInterval;         //!< time interval between stats updates in seconds, 1.0 second by default;
 272                                                                  //!  too often updates might impact performance and will smear text within widgets
 273                                                                  //!  (especially framerate, which is better averaging);
 274                                                                  //!  0.0 interval will force updating on each frame
 275   Standard_Integer                  StatsTextHeight;             //!< stats text size; 16 by default
 276   Standard_Integer                  StatsNbFrames;               //!< number of data frames to collect history; 1 by default
 277   Standard_ShortReal                StatsMaxChartTime;           //!< upper time limit within frame chart in seconds; 0.1 seconds by default (100 ms or 10 FPS)
 278   PerfCounters                      CollectedStats;              //!< performance counters to collect, PerfCounters_Basic by default;
 279                                                                  //!  too verbose options might impact rendering performance,
 280                                                                  //!  because some counters might lack caching optimization (and will require expensive iteration through all data structures)
 281   Standard_Boolean                  ToShowStats;                 //!< display performance statistics, FALSE by default;
 282                                                                  //!  note that counters specified within CollectedStats will be updated nevertheless
 283                                                                  //!  of visibility of widget managed by ToShowStats flag (e.g. stats can be retrieved by application for displaying using other methods)
 284
 285 };
 286
 287 #endif // _Graphic3d_RenderingParams_HeaderFile