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

The simplest geometric primitive in |HPSNOW| 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, |HPSNOW| 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, |HPSNOW| 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.


