===========
Definitions
===========

A definition is the name for any of the resources that are stored in a portfolio. There are eight types of definitions:

.. csv-table::
	:header: "Definition", "Description"
	
	"``HPS::NamedStyleDefinition``", "A named group of attributes applied to a segment as opposed to setting attributes individually. See :ref:`this section <prog_guide/0403_styles:Named styles>` for details."
	"``HPS::GlyphDefinition``", "A simple geometric symbol used for styling markers, vertices and lines. For an in-depth discussion on glyphs, see our section on :doc:`glyphs <0405_glyphs>`."
	"``HPS::ImageDefinition``", "A two dimensional array of pixel data used as source for textures. See :doc:`this section <0404_images>` for an example on how to load an image into a portfolio."
	"``HPS::TextureDefinition``", "A description of how an image source will be applied to a given facetted surface. For more details on how to load and use textures, see :doc:`this page <0503_textures>`."
	"``HPS::LinePatternDefinition``", "A description of how a line is rendered using patterned lines, glyphs, and end caps. Line patterns are discussed :doc:`here <0406_line_patterns>`."
	"``HPS::MaterialPaletteDefinition``", "A collection of materials that can be referenced by index. A palette can be used to apply materials to facetted geometry. Material palettes are discussed :ref:`here <prog_guide/0501_materials_introduction:Defining material palettes>`."
	"``HPS::CubeMapDefinition``", "A texture definition composed of six images that correspond to the faces of a cube. Typically used to render background scenery with the viewpoint at the center of the cube. See the example in :doc:`this section <0503_textures>`."

Most definitions are created by passing the corresponding kit to the portfolio where the definition will be contained. It is recommended that a descriptive name be used for the definition since all definitions are referred to by name. However, this is not a requirement and you can create nameless definitions by passing an empty string or ``null_ptr`` as the name.

After the resources are defined, they are accessible by any segment that is using the portfolio. Similarly, definitions can be undefined.

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_definitions.cs
		   :start-after: //! [example_definitions]
		   :end-before: //! [example_definitions]
		   
In addition to creating definitions, you can also import them from other portfolios. When importing, there are three layers of granularity. You can import all the definitions from a portfolio, all definitions for a specific category, or individual definitions. When you import definitions from another portfolio, use the portfolio key:

.. tabs::

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

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_definitions.cs
		   :start-after: //! [import_all]
		   :end-before: //! [import_all]
		   
All of the ``Import`` functions have a second parameter which defaults to ``true``. This flag controls whether the definitions that are being imported will replace the existing definitions.

.. tabs::

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

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