======
Glyphs
======

A glyph is a defined symbol used to represent a :doc:`marker <0207_markers>`, a :doc:`shell <0201_shells>` vertex, an element in a :doc:`line pattern <0406_line_patterns>`, or a :ref:`line endpoint <prog_guide/0205_lines:End caps and joins>` such as an arrowhead.

Each |HPSNOW| segment has its own attribute setting for the current marker symbol. As glyphs are used as marker symbols, it follows that in order to use different glyphs as markers, you must use different segments. |HPSNOW| comes with a number of glyphs predefined and ready to use. A list of these glyphs can be found in the :doc:`appendix <appendix_default_glyphs>`. Before using a pre-defined glyph, you must import it into the active portfolio. The code sample below demonstrates how to set a glyph as the current marker symbol and insert the marker at the origin:

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_using_glyphs.cs
		   :start-after: //! [basic_glyph_usage]
		   :end-before: //! [basic_glyph_usage]
		   

.. _custom:

Custom Glyphs
=============

If the set of predefined glyphs is not sufficient, you can create a custom glyph. The following section demonstrates how to do that.

Glyphs are composed of one or more ``HPS::GlyphElement`` objects which are used to draw the lines, dots, and curves of the glyph. These elements can be any of the following:

.. csv-table::
	:header: "Geometry type", "Associated class"
	
	"circular arcs", "``HPS::CircularArcGlyphElement``"
	"ellipses", "``HPS::EllipseGlyphElement``"
	"lines", "``HPS::LineGlyphElement``"
	"infinite lines", "``HPS::InfiniteLineGlyphElement``"
	"individual pixels", "``HPS::DotGlyphElement``"

Attribute settings for glyphs include color and fill and are set at the attribute level. Glyphs are programmatically defined as shown in the following steps:


Step 1: Segment Structure
-------------------------

As glyph settings affect glyphs at the segment-level, it is important to arrange the scene hierarchy to achieve the desired result. For this example, a new segment is created in order to make a glyph in the shape of a modified X. A new ``HPS::GlyphKit`` is also initialized.

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_defining_glyphs.cs
		   :start-after: //! [defining_glyphs_step1]
		   :end-before: //! [defining_glyphs_step1]
		   
		   
Step 2: Set the Glyph Canvas
----------------------------

All glyphs have an associated drawing canvas, the maximum size of which is 256 x 256 units. Although glyphs are rectangular in shape, each one has a "radius" which sets the drawable area. The glyph offset must also be set. This locates the origin of the glyph coordinate system relative to the center of the glyph. For example, the following code sets a drawable area of -100 to 100 in both **x** and **y** directions, and additionally creates an offset of zero, leaving the origin in the center of the glyph.

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_defining_glyphs.cs
		   :start-after: //! [defining_glyphs_step2]
		   :end-before: //! [defining_glyphs_step2]
		   

Step 3: Set the Glyph Geometry
------------------------------

This glyph will be drawn using lines, so the ``HPS::LineGlyphElement`` will be used. This class requires a series of ``HPS::GlyphPoint`` objects to build the line. There can be any number of line glyph elements in a single glyph, but for this example, only one is needed. The result is a sort of polyline. Note that the color is set at the element level using ``SetExplicitColor``.

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_defining_glyphs.cs
		   :start-after: //! [defining_glyphs_step3]
		   :end-before: //! [defining_glyphs_step3]
		   

Step 4: Assemble the GlyphElements into an Array
------------------------------------------------

For a glyph that is composed of multiple elements, assembling the glyph elements into a collection seems more natural. However, regardless of the number of elements, the ``HPS::GlyphElementArray`` is necessary, even for a single element:

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_defining_glyphs.cs
		   :start-after: //! [defining_glyphs_step4]
		   :end-before: //! [defining_glyphs_step4]
		   
		   
Step 5: Define the Glyph in a Portfolio
---------------------------------------

All glyphs must be associated with a portfolio, and this portfolio must be made active for the segment that will display the glyph. Give your glyph a descriptive name if there is any possibility of ambiguity. Portfolios are discussed in detail in :doc:`here <0401_portfolios_introduction>`.

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_defining_glyphs.cs
		   :start-after: //! [defining_glyphs_step5]
		   :end-before: //! [defining_glyphs_step5]
		   

Step 6: Custom Glyph is Ready to Use
------------------------------------

At this point, the glyph is imported into |HPSNOW| and is ready to use. To insert it as a marker, be sure to make it the active marker symbol:

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_defining_glyphs.cs
		   :start-after: //! [defining_glyphs_step6]
		   :end-before: //! [defining_glyphs_step6]
		   
.. image:: images/custom_glyph.png

*The custom glyph*


.. _image_glyphs:

Images as Glyphs
================

|HPSNOW| also allows you to create a glyph from a :doc:`defined image <0404_images>`. The process is similar to creating a custom glyph as described in the previous section, except you would use the defined image as the source of a glyph element. When you define an image as a glyph element, it can be combined with other types of glyph elements to create complex glyphs. 

One important difference when using image glyphs is setting the glyph radius. Normally, this value is used as the size of the "canvas" on which the glyph is drawn. With image glyphs, the radius is internally computed based on the image size. However, you must still call ``SetRadius(0)`` to initialize the glyph element properly.

The code below shows how to create a glyph from an image:

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_image_glyphs.cs
		   :start-after: //! [image_glyphs]
		   :end-before: //! [image_glyphs]
