==================
Reference geometry
==================

HOOPS supports the reuse of segments via the ``HC_Include_Segment`` method.  Organizing your scene tree by using :ref:`include segments <prog_guide/3dgs/01_3_database_dbase_structure:Include segments>` lets you make better use of your memory. However, sometimes you might want to only refer to a specific piece of geometry in a given segment and set attributes that are relevant to that part of the scene graph.  

HOOPS provides the functionality to do this via the ``HC_Reference_Geometry`` method. Referencing geometry provides a degree more flexibility than including an entire segment because you can instance only the geometry that you need. Once it is referenced, you can set any number of attributes on the referenced geometry while an include segment cannot have any attributes or options set on it directly.

For instance, if you were to build a scene depicting the assembly line for a mountain bike, you could create a single segment in your library that contains the geometry for all the different screws for the bike.  To add one of the screws to your scene, you could instance it via the ``HC_Reference_Geometry`` method and apply any necessary attributes like a rotation matrix. If the scene has six M6 x 16mm hex screws in it, you would only need to create the screw once in your library and reference it six times in your scene graph.

The following is a sample code for how to reference a piece of geometry and then set attributes on it::
		   
	HC_KEY HexScrewKey = HC_KInsert_Shell(...);

	HC_Open_Segment("Screw and Bolt")
		HC_KEY ref_key = HC_KReference_Geometry_By_Key (HexScrewKey);
		HC_Open_Geometry (ref_key);
		HC_Translate_Object (-0.5, 0.5, 0.0);
		HC_Set_Color ("black");
		HC_Close_Geometry ();
	HC_Close_Segment();
