=======
Markers
=======

The simplest geometric primitive in HOOPS Visualize is a marker, which is used to represent a point in space. With :ref:`one exception <prog_guide/0201_shells:3d markers>`, markers are two-dimensional geometry with the marker always oriented to face the camera, but can be positioned anywhere in 3D space.

A marker is visually represented by a marker symbol, or :doc:`glyph <0405_glyphs>`, which is a segment-level attribute. A set of :doc:`default glyphs <appendix_default_glyphs>` are provided.

The default marker symbol is a small filled circle, and the default marker visibility setting is *off* (see :ref:`this section <color_and_visibility>` for instructions on enabling marker visibility). The marker symbol is set using ``HPS::MarkerAttributeControl::SetSymbol`` as demonstrated in this snippet:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_markers.cpp
		   :start-after: //! [0202_a]
		   :end-before: //! [0202_a]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_markers.cs
		   :start-after: //! [0202_a]
		   :end-before: //! [0202_a]

Like other geometry, markers can be inserted using a ``HPS::MarkerKit``. However, the benefit to doing this is limited as there is only one parameter to set, the position. It should be noted that a segment's active marker symbol is also used to draw geometry vertices for shells and meshes.

When possible, Visualize will use hardware paths to draw markers. However, this means we sometimes run into the situation where the hardware has a maximal size for hardware markers - any markers larger than this are shrunk to the hardware maximum. This setting should be left at the default value of ``Marker::DrawingPreference::Fastest`` in all cases unless such a problem is directly seen, in which case ``Marker::DrawingPreference::Nicest`` can be used to ensure markers are drawn properly. As this incurs a performance cost, we recommend only setting ``Nicest`` at the segment where the too-large markers live, and to set Fastest in all other places.

.. _marker_size:

Marker Size
===========

Marker size is controlled by calling ``HPS::MarkerAttributeControl::SetSize``. Note the default size is fixed - the marker will not change size due to camera or modelling matrix changes. If no marker size-unit parameter is given when calling ``HPS::MarkerAttributeControl::SetSize``, the marker is linearly scaled by the default marker size. Note that several of the marker size-units will result in 'view-dependent' sizing, where the marker size will change as the camera or modelling matrices change.

For example, to set the marker size to 5 pixels, use the ``HPS::Marker::SizeUnits::Pixels`` enum. To scale the marker in world coordinates, use ``HPS::Marker::SizeUnits::WorldSpace``.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_markers.cpp
		   :start-after: //! [020201_a]
		   :end-before: //! [020201_a]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_markers.cs
		   :start-after: //! [020201_a]
		   :end-before: //! [020201_a]
		   
.. image:: images/marker_size.png

*Marker size is controlled using the ``MarkerAttributeControl``*


**NOTE:** The "Dot" marker symbol is a special case and cannot be resized.

.. _drawing_preference:

In the code snippet above, an enum ``HPS::Marker::DrawingPreference`` has been applied to the markers' attributes. When possible, Visualize will use hardware paths to draw markers. However, this means we sometimes run into the situation where the hardware has a maximal size for hardware markers - any markers larger than this are shrunk to the hardware maximum.

This setting should be left at the default value of ``HPS::Marker::DrawingPreference::Fastest`` in all cases unless markers are appearing smaller than desired on certain hardware, in which case ``HPS::Marker::DrawingPreference::Nicest`` can be used to ensure markers are drawn at the proper size. Because this incurs a performance cost, we recommend only setting ``HPS::Marker::DrawingPreference::Nicest`` at the segment where the oversize markers live, and to set ``HPS::Marker::DrawingPreference::Fastest`` in all other places.


.. _editing_markers:

Editing Markers
===============

As with other geometry, markers can be modified after insertion by using the marker's key. However, the actions available for modifying a marker are limited:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_markers.cpp
		   :start-after: //! [020202_a]
		   :end-before: //! [020202_a]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_markers.cs
		   :start-after: //! [020202_a]
		   :end-before: //! [020202_a]
		   
.. image:: images/editing_markers.png

*'marker2' has been edited using the code above*


.. _color_and_visibility:

Marker Color and Visibility
===========================

Marker color is controlled at the segment level using the ``HPS::MaterialMappingControl`` (for a discussion on materials, see :doc:`this section <0501_materials_introduction>`). To toggle the visibility of markers, use the ``HPS::VisibilityControl`` of the segment key:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_markers.cpp
		   :start-after: //! [020203_a]
		   :end-before: //! [020203_a]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_markers.cs
		   :start-after: //! [020203_a]
		   :end-before: //! [020203_a]
		   
		   
.. _other_considerations:

Other Considerations When Using Markers
=======================================

For applications that require markers in a grid pattern, it is possible to insert multiple markers using a mesh with face and edge visibility turned off. This technique is slightly more efficient in terms of space, and produces identical results. The mesh primitive is discussed :doc:`here <0202_meshes>`.

If you have inserted a large number of markers into your scene (on the order of 10,000 or more), we suggest that you explore using :ref:`vertex markers <prog_guide/0201_shells:Vertex markers>` as an alternative way to represent your data. This approach will result in more efficient rendering and lower memory usage.


