=======
Spheres
=======

Visualize supports a sphere primitive. It is tessellated at draw time which can greatly reduce the memory footprint of your application if spheres are widely used. It is inserted via a center point, radius, and vertical-horizontal vectors. When invoking ``HPS::SegmentKey::InsertSphere`` with a ``HPS::SphereKit object``, the basis vectors are required in order for the sphere to be visible.  Including basis vectors also allows for easier application of a texture. A sphere that is tessellated using vertical and horizontal vectors has 'poles' and thus a texture can be applied by wrapping it around the sphere as you would around a cylinder. A sample call is as follows:

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_spheres.cs
		   :start-after: //! [0210_a]
		   :end-before: //! [0210_a]
		   
.. image:: images/basic_sphere.png

*A basic sphere*


Sphere tessellation can also be controlled with the segment's ``HPS::SphereAttributeControl``. The tessellation setting controls the number of faces around the equator of the sphere.

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_spheres.cs
		   :start-after: //! [0210_b]
		   :end-before: //! [0210_b]
		   
.. image:: images/tessellated_sphere.png

*A sphere with a high tesselation value*


Notes on Sphere Sub-Entities
----------------------------

Spheres, like cylinders, are dynamically constructed Visualize primitives. One result of this is that user interaction among subentites is limited. For instance, setting attributes or materials on individual faces, lines, or vertices is not supported nor is altering their position. Cylinder and sphere primitives cannot be textured.

