##########
Draw Modes
##########

Overview
========

The HOOPS Web Viewer component supports several different ways to draw the scene called "Draw Modes". Only one of them can be active at a given time. To activate a specific draw mode call the :ref:`setDrawMode() <api_ref/viewing/classes/Communicator.View:setdrawmode>` function on the view object:

.. literalinclude:: /../../applications/client/docs/PG_Viewing_drawmodes.ts
   :start-after: //! [webviewer_setDrawModeShaded]
   :end-before: //! [webviewer_setDrawModeShaded]

The following draw modes are currently supported:

* Gooch
* HiddenLine
* Shaded
* Toon
* Wireframe
* WireframeOnShaded
* XRay

Visit the :doc:`DrawMode </api_ref/viewing/enums/Communicator.DrawMode>` entry in our API Reference Manual for more details.

Selecting one of those draw modes renders the scene with either faces and lines turned on, faces only or lines only. It is an easy way to turn off visibility of faces and lines for the whole model. Alternatively you can also use the functions :ref:`view.setLineVisibility() <api_ref/viewing/classes/Communicator.View:setlinevisibility>` and :ref:`view.setFaceVisibility() <api_ref/viewing/classes/Communicator.View:setfacevisibility>` to control this behavior. The code below turns on Wireframe mode meaning that only the lines in the model are displayed:

.. literalinclude:: /../../applications/client/docs/PG_Viewing_drawmodes.ts
   :start-after: //! [webviewer_setDrawModeWireframe]
   :end-before: //! [webviewer_setDrawModeWireframe]
   
.. image:: images/draw_modes_wireframe_on_shaded.png

*Wireframe draw mode on*


Hidden line
===========

Hidden line removal (HLR) involves displaying only visible, unobscured lines. Faces of visible geometry will be used to obscure lines the lines in the model or draw them in a dimmed style but the faces themselves will not be drawn. Typically, HLR is used to provide a result suitable for hardcopy or screenshots since having shaded facets can clutter the scene. However, sometimes end-users are also interested in seeing a model rendered with hidden line mode on the screen.

.. literalinclude:: /../../applications/client/docs/PG_Viewing_drawmodes.ts
   :start-after: //! [webviewer_setDrawModeHiddenLine]
   :end-before: //! [webviewer_setDrawModeHiddenLine]

.. image:: images/draw_modes_hidden_line.png

*Hidden line mode on*

There are various settings for hidden line mode that you can specify by retrieving and modifying the :doc:`HiddenLineSettings </api_ref/viewing/classes/Communicator.Settings.HiddenLineSettings>` object. For example, in order to make the obscured lines in the hidden line render invisible you would write the following code:

.. literalinclude:: /../../applications/client/docs/PG_Viewing_drawmodes.ts
   :start-after: //! [webviewer_setDrawModeHiddenLineSettings]
   :end-before: //! [webviewer_setDrawModeHiddenLineSettings]

.. image:: images/draw_modes_hidden_line_obscured_invisible.png

*Hidden line mode on w/ obscured lines*


Hard edge detection
===================

A hard edge detection algorithm is enabled by *default*. This new algorithm will cause hidden line mode to look different than previous versions. A new set of functions have been added to the :doc:`View class </api_ref/viewing/classes/Communicator.View>` to control this new behavior.

* :ref:`setHardEdgesEnabled() <api_ref/viewing/classes/Communicator.View:sethardedgesenabled>`, :ref:`getHardEdgesEnabled() <api_ref/viewing/classes/Communicator.View:gethardedgesenabled>`
* :ref:`setHardEdgeColor() <api_ref/viewing/classes/Communicator.View:sethardedgecolor>`, :ref:`getHardEdgeColor() <api_ref/viewing/classes/Communicator.View:gethardedgecolor>`
* :ref:`setHardEdgeOpacity() <api_ref/viewing/classes/Communicator.View:sethardedgeopacity>`, :ref:`getHardEdgeOpacity() <api_ref/viewing/classes/Communicator.View:gethardedgeopacity>`
* :ref:`setHardEdgeThreshold() <api_ref/viewing/classes/Communicator.View:sethardedgethreshold>`, :ref:`getHardEdgeThreshold() <api_ref/viewing/classes/Communicator.View:gethardedgethreshold>`
* :ref:`setHardEdgeThresholdRampWidth() <api_ref/viewing/classes/Communicator.View:sethardedgethresholdrampwidth>`, :ref:`getHardEdgeThresholdRampWidth() <api_ref/viewing/classes/Communicator.View:gethardedgethresholdrampwidth>`

.. image:: images/prototype-hard-edges-on.png

*Default - hard edges on:*

.. image:: images/prototype-hard-edges-off.png

*Hard edges off*


X-ray
=====

The purpose of X-ray mode is to make it easy to identify selected elements in a complex scene by turning the whole model except for the selected elements transparent. In the below example the selected part is inside the model and would normally just be displayed as an outline. With X-ray mode however the selected part is fully displayed without completely hiding the rest of the model.

.. image:: images/draw_modes_x_ray.png

*X-ray mode on*

Below are the API functions to control various aspects of X-ray mode:

* :ref:`view.setXRayColor() <api_ref/viewing/classes/Communicator.View:setxraycolor>`
* :ref:`view.setXRayOpacity() <api_ref/viewing/classes/Communicator.View:setxrayopacity>`
* :ref:`view.setXRayTransparencyMode() <api_ref/viewing/classes/Communicator.View:setxraytransparencymode>`

As an example, let's change the opacity of the unselected lines to fully opaque:

.. literalinclude:: /../../applications/client/docs/PG_Viewing_drawmodes.ts
   :start-after: //! [webviewer_setDrawModeXRayOpacity]
   :end-before: //! [webviewer_setDrawModeXRayOpacity]

.. image:: images/draw_modes_x_ray_opacity.png

*X-ray mode on with opaque unselected lines*
