=======
Samples
=======

The following is a list of code samples available to HOOPS Visualize developers. These samples are short snippets that demonstrate a specific functional topic. The source code for each sample is distributed as part of the Visualize package. The sample sources are located at *<HPS_INSTALL_DIR>/samples/code/*. To run a specific sample, you must first build the samples project. Then, execute the program and specify the sample name on the command line. Optionally, you can provide a driver to use as well.

For example, to run the "bloom_silhouette" sample using the OpenGL2 driver:

``hps_samples.exe -t bloom_silhouette -d OpenGL2``

----------------------------

bloom_Silhouette
================

bloom_silhouette.cpp / bloom_silhouette.cs

This sample shows the user how to:

* Load an HSF file and check for exceptions
* Obtain a ``HPS::PostProcessEffectsControl`` object
* Setting bloom and fast silhouette edges

See also: Programming Guide section on :doc:`bloom </prog_guide/0804_bloom>` and :doc:`silhouette edges </prog_guide/0809_advanced_edges>`.

----------------------------

Complex_Clip_Regions
====================

complex_clip_regions.cpp / complex_clip_regions.cs

This sample shows the user how to:

* Create a grid and use a complex clip region to clip it

See also: Programming Guide section on :doc:`clip regions </prog_guide/0305_clip_regions>`.

----------------------------

Conditional_Styles_and_Includes
===============================

conditional_styles_and_includes.cpp / conditional_styles_and_includes.cs

This sample shows the user how to:

* Set styles only when certain conditions are met
* Include geometry only when certain conditions are met
* Create named styles
* Build complex conditions using logical operators

See also: Programming Guide section on :doc:`styles </prog_guide/0403_styles>`.


----------------------------

custom_Event
============

custom_event.cpp / custom_event.cs

This sample shows the user how to:

* Create a custom event
* Create a custom event handler
* Register an event
* Get an event dispatcher and subscribe it to the custom event
* Inject the custom event with a notifier
* Wait for the event handling thread to terminate

See also: Programming Guide section on :doc:`custom events </prog_guide/1002_custom_events>`.

----------------------------

Database_Search
===============

database_search.cpp / database_search.cs

This sample shows the user how to:

* Load an HSF file and check for exceptions
* Search the database for segments, shells, and vertices
* Obtain a ``HPS::SearchResultsIterator`` object, and how to walk a search result list with the iterator
* Inserting text through ``HPS::UTF8`` objects
* Setting a camera through a ``HPS::CameraKit`` object

See also: Programming Guide sections about :doc:`database searching </prog_guide/0101_database>` and :doc:`cameras </prog_guide/0303_cameras>`.

----------------------------

.. only:: not spatial

	Exchange_Component_Highlighting
	===============================

	exchange_component_highlighting.cpp / exchange_component_highlighting.cs

	This sample shows the user how to:

	* Walk the component structure of a ``HPS::CADModel``
	* Highlight a specific instance of a component
	* Highlight all instances of a component
	* Build a ``HPS::KeyPath``
	* Define a named style used for highlighting

	See also: Programming Guide sections about :ref:`API conventions <prog_guide/0102_api_conventions:Using keys and objects>`, :doc:`highlighting </prog_guide/0604_highlighting>`.

	----------------------------

.. only:: not spatial

	Exchange_Component_Interaction
	==============================

	exchange_component_interaction.cpp / exchange_component_interaction.cs

	This sample shows the user how to:

	* Import an Exchange file and check for exceptions
	* Traverse the component structure of a ``HPS::CADModel``
	* Obtain a component from a selection event
	* Highlight a selected component
	* Define named styles and glyphs

	See also: Programming Guide sections about :doc:`selection </prog_guide/0603_selection>`, :doc:`highlighting </prog_guide/0604_highlighting>`, :doc:`styles </prog_guide/0403_styles>`, :doc:`glyphs </prog_guide/0405_glyphs>`.

	----------------------------

.. only:: not spatial

	Exchange_PMI_Highlighting
	=========================

	exchange_pmi_highlighting.cpp / exchange_pmi_highlighting.cs

	This sample shows the user how to:

	* Load an Exchange file and check for IO exceptions
	* Walk down a component structure
	* Verify the type of a component
	* Defining named styles
	* Highlighting PMIs and geometry referenced by a particular PMI component
	* Hide components using highlighting
	* Use a ``HPS::KeyPath`` to operate on a particular instance of geometry

	See also: Programming Guide sections about :ref:`using keys <prog_guide/0102_api_conventions:Using keys and objects>`, :doc:`highlighting </prog_guide/0604_highlighting>`.

	----------------------------

.. only:: not spatial

	Exchange_Publish
	================

	exchange_publish.cpp / exchange_publish.cs

	This sample shows the user how to:

	* Load an Exchange file through ``HPS::Exchange`` and check for Exchange IO exceptions
	* Output a 3D PDF file through ``HPS::Publish`` and check for Exchange IO exceptions

	See also: Programming Guide sections about :doc:`HOOPS Exchange </prog_guide/0906_exchange_integration>` and :doc:`HOOPS Publish </prog_guide/0905_publish_integration>` integration.

	----------------------------

Hardcopy_Export
===============

hardcopy_export.cpp / hardcopy_export.cs

This sample shows the user how to:

* Import an HSF file
* Retrieve the size of the window at runtime
* Export a 2D-PDF and PostScript file
* Check whether the hardcopy export completed successfully

----------------------------

Hidden_Line
===========

hidden_line.cpp / hidden_line.cs

This sample shows the user how to:

* Load an HSF file and check for exceptions
* Tweak segment level visibility using a ``HPS::VisibilityControl`` object
* Change the rendering algorithm to ``HPS::HiddenLine``
* Obtain a ``HPS::HiddenLineAttributeControl`` and several options which can be modified from it.

See also: Programming Guide section about :doc:`hidden surface removal </prog_guide/0807_hidden_surface_removal>`.

----------------------------

Hidden_Line_Advanced
====================

hidden_line_advanced.cpp / hidden_line_advanced.cs

This sample shows the user how to:

* Load an HSF file and check for exceptions
* Tweak segment level visibility using a ``HPS::VisibilityControl`` object
* Set up a drawing to use hidden lines with shadows

See also: Programming Guide section about :doc:`hidden surface removal </prog_guide/0807_hidden_surface_removal>`.

----------------------------

Highlighting
============

highlighting.cpp / highlighting.cs

This sample shows the user how to:

* Load an HSF file
* Load an image and use it to create a texture
* Create an opaque style
* Create a transparent style
* Create a textured style

See also: Programming Guide sections about :doc:`styles </prog_guide/0403_styles>` and :doc:`highlighting </prog_guide/0604_highlighting>`.

----------------------------

Image_Background
================

image_background.cpp / image_background.cs

This sample shows the user how to:

* Load an HSF file and check for exceptions
* Search portfolio objects for image definitions
* Applying portfolios to segments
* Searching a list of named images
* Applying an image as the window background

See also: Programming Guide sections about :doc:`portfolios </prog_guide/0401_portfolios_introduction>` and :doc:`subwindows </prog_guide/0304_subwindows>`.

----------------------------

Image_IO
========

image_io.cpp / image_io.cs

This sample shows the user how to:

* Load a JPG file through ``HPS::Image`` and check for Image IO exceptions
* Obtain an ``HPS::ImageKit`` and how to interact with it (obtain image size, image data, etc)
* Convert an image between formats
* Output an image to a file
* Insert text using ``HPS::UTF8`` objects

See also: Programming Guide section about :doc:`importing </prog_guide/0901_importing_files>`.

----------------------------

Image_Output
============

image_output.cpp / image_output.cs

This sample shows the user how to:

* Load an HSF file and check for exceptions
* Create an offscreen window
* Render to an offscreen window
* Save a snapshot to disk

See also: Programming Guide section about :doc:`offscreen rendering </prog_guide/0702_offscreen_rendering>`.

----------------------------

Insert_Cube
===========

insert_cube.cpp / insert_cube.cs

This sample shows the user how to:

* Insert a basic cube

See also: Programming Guide section about :doc:`shells </prog_guide/0201_shells>`.

----------------------------

Interpolation
=============

interpolation.cpp / interpolation.cs

This sample shows the user how to:

* Create a material palette
* Set colors on vertices using an ``HPS::RGBColor``
* Set colors on vertices using a material palette
* Turning color interpolation on and off

See also: Programming Guide sections about :doc:`materials </prog_guide/0501_materials_introduction>` and :doc:`color interpolation </prog_guide/0806_color_interpolation>`.

----------------------------

Lightweight_Subwindow
=====================

lightweight_subwindow.cpp / lightweight_subwindow.cs

This sample shows the user how to:

* Load an HSF file and check for exceptions
* Set up a legend, with a separate camera on the legend segment
* Use of depth range and exclude bounding

----------------------------

Mask_Transforms
===============

mask_transforms.cpp / mask_transforms.cs

This sample shows the user how to:

* Insert a shell
* Mask modelling matrix rotation, scaling, and translation
* Rotate, scale, and translate a scene

See also: Programming Guide section about :ref:`transform masks <prog_guide/0303_cameras:Transform masks>`.

----------------------------

Meshes
======

meshes.cpp / meshes.cs

This sample shows the user how to:

* Insert a mesh
* Set the normals on a mesh
* Include segments into other segments
* Set segment level attributes (color)
* Change the modelling matrix

See also: Programming Guide section about :doc:`meshes </prog_guide/0202_meshes>`.

----------------------------

Nvidia_Profile_Creator
======================

This sample and associated project can be found in the *hps/samples/nvapi_profile_creator* directory.

This sample helps address the limitations of GPU selection using ``SetPreferredGPU()``. *nvidia_profile_creator* demonstrates how to programmatically create an application profile that will make the NVIDIA GPU the preferred GPU for a particular application. As such, this method for GPU selection will only work on laptops with NVIDIA GPUs, and it will only work on Windows.

This is the programmatic equivalent to launching the NVIDIA Control Panel, adding a new application, and setting this preference via its GUI. This allows the discrete GPU to get used for any driver, and will work for ``D3DImageCanvas`` as well.

This new sample requires the NVAPI SDK which can be found here: `https://developer.nvidia.com/nvapi <https://developer.nvidia.com/nvapi>`_. It is free, but will require acceptance of a license agreement and a free NVIDIA Developer Account. You will need to define an environment variable named *NVAPI_DIR* which points to the extracted location.

This sample shows the user how to:

* Initialize the NVAPI.
* Create a new profile with given name.
* Delete an existing profile of a given name.
* Add an application to the new profile.
* Add the settings which will make the NVIDIA GPU the preferred GPU for that application.
* Save the profile so it will be used when the application is next launched.

Note that for the profile to have an effect, it must exist prior to launching an application. If an application is already launched prior to the creation of the profile, it will need to be closed and launched again after the profile is created.

We recommend running this profile creation code as a step in your installer, or as a utility to run on demand.

----------------------------

Priority
========

priority.cpp / priority.cs

This sample shows the user how to:

* Control the drawing order of co-planar geometry using ``SetPriority()``

See also: Programming Guide section about :ref:`hidden surface removal <prog_guide/0807_hidden_surface_removal:2D and wireframe scenes>`.

----------------------------

.. only:: not spatial

	Publish_Widgets
	===============

	publish_widgets.cpp / 	publish_widgets.cs

	This sample shows the user how to:

	* Create a PDF file and insert a check box, button, and list box using HOOPS Publish
	* Demonstrate how to connect Javascript to a button
	* Output a the file through Publish and check for IO exceptions

	See also: Programming Guide section about :doc:`HOOPS Publish </prog_guide/0905_publish_integration>`.

	----------------------------

Quickmoves
==========

quickmoves.cpp / quickmoves.cs

This sample shows the user how to:

* Load an HSF file and check for exceptions
* Include segments into other segments
* Setting different overlay settings (no overlay, normal overlay, overlay with z-value)
* Shows performance difference between overlay styles

See also: Programming Guide section on :doc:`overlays </prog_guide/0605_overlays>`.

----------------------------

Reference_Geometry
==================

reference_geometry.cpp / reference_geometry.cs

This sample shows the user how to:

* Load an HSF file which contains a shell
* Search the segment tree for the shell
* Use reference geometry to instance the shell multiple times

See also: Programming Guide section on :doc:`reference geometry </prog_guide/0214_reference_geometry>`.

----------------------------

Render_Modes
============

render_modes.cpp / render_modes.cs

This sample shows the user how to:

* Load an HSF file and check for exceptions
* Divide the screen into subwindows
* Include segments into other segments
* Render with flat shading, wireframe, hidden line, Gouraud, Phong algorithms
* Use color index interpolation

See also: Programming Guide section about :doc:`lighting interpolation </prog_guide/0805_lighting_interpolation>`.

----------------------------

Segment_Attributes
==================

segment_attributes.cpp / segment_attributes.cs

This sample shows the user how to:

* Insert a shell
* Include a segment
* Correctly delete included geometry
* Change segment level attributes (face color, edge color, face visibility, edge visibility)
* Use transparency
* Use subwindows

See also: Programming Guide sections about :doc:`database attributes </prog_guide/0101_database>` and :doc:`subwindows </prog_guide/0304_subwindows>`.

----------------------------

Select_by_Point
===============

select_by_point.cpp / select_by_point.cs

This sample shows the user how to:

* Perform an analytic selection
* Perform a visual selection

See also: Programming Guide section on :doc:`selection </prog_guide/0603_selection>` - see "selection" sample.

----------------------------

Shell_Attributes
================

shell_attributes.cpp / shell_attributes.cs

This sample shows the user how to:

* Insert a shell
* Include a segment
* Change shell level attributes (face color, vertex color, vertex visibility, face visibility)

See also: Programming Guide section about :doc:`shells </prog_guide/0201_shells>`.

----------------------------

Selection
=========

selection.cpp / selection.cs

This sample shows the user how to:

* Load an HSF file and check for IO exceptions
* Define a glyph to be used as a marker symbol
* Define a named style
* Select a single instance of an entity
* Modify selection option and selectability
* Highlight selected geometry

See also: Programming Guide sections about :doc:`selection </prog_guide/0603_selection>`, :doc:`highlighting </prog_guide/0604_highlighting>`, :doc:`styles </prog_guide/0403_styles>`, and :doc:`glyphs </prog_guide/0405_glyphs>`.

----------------------------

Spacemouseoperator
==================

The source for this sample, *sprk_space_mouse_op.h* and *sprk_space_mouse_op.cpp*, can be found in your HOOPS Visualize package in the *samples/operators* directory.

This sample shows the user how to write a custom operator for the Space Mouse, which is a type of mouse manufactured by 3DConnexion. The Space Mouse allows for 6 degrees of freedom. It can be used to pan, orbit, zoom, and select all at once.

Another common workflow is to have both a regular mouse and a space mouse connected at the same time, and to use them simultaneously, one in each hand.

Please note that due to the fact that the Space Mouse operator depends on DirectX, there are additional prerequisites you need to satisfy in order to run this sample:

#. Obtain and install the drivers from 3DConnexion.
#. The sample requires XInput, so you must link against *XInput.lib*, which is part of DirectX.
#. In your development environment, add *sprk_space_mouse_op.h* and *sprk_space_mouse_op.cpp* to the samples project. The directory where they are located will need to be added to the project list of include directories.
#. If your project uses pre-compiled headers, *sprk_space_mouse_op.cpp* should be set to not use them.

The operator responds to the following commands:

* Pushing the mouse left and right will translate the model.
* Pulling up on the mouse will translate the model up, pushing the mouse down will translate the model down.
* Pushing the mouse forward will zoom out, pulling the mouse towards you will zoom in.
* Tilting the mouse will rotate the model around the axis you are tiling on.
* In debug mode, pressing a button will output a debug message saying which button was pressed or released.

The sample only works with C++.

See also: Programming Guide sections about :doc:`standard operators </prog_guide/0601_standard_operators>` and :doc:`custom operators </prog_guide/0602_custom_operators>`.

----------------------------

Spotlight
=========

spotlight.cpp / spotlight.cs

This sample shows the user how to:

* Insert a shell
* Set segment level attributes (color)
* Insert a spotlight

See also: Programming Guide section about :doc:`spotlights </prog_guide/0204_lights>`.

----------------------------

Subshell_Attributes
===================

sub_shell_attributes.cpp / sub_shell_attributes.cs

This sample shows the user how to:

* Insert a shell
* Divide the screen into sub-windows
* Change shell-level attributes

See also: Programming Guide section about :ref:`applying materials <prog_guide/0504_applying_materials:Applying materials at various levels>`.

----------------------------

Textures
========

textures.cpp / textures.cs

This sample shows the user how to:

* Load an HSF file and check for exceptions
* Load an image file through ``HPS::Image`` and check for Image IO exceptions
* Search the database for segments, and iterate through a list of search results
* Create a portfolio
* Define textures with sphere, cylinder and UV parameterizations
* Apply textures to geometry

See also: Programming Guide sections about :doc:`portfolios </prog_guide/0401_portfolios_introduction>`, :ref:`materials <prog_guide/0501_materials_introduction:Defining material palettes>`, and :doc:`textures </prog_guide/0503_textures>`.
