########
Examples
########

Included in the Communicator package are a number of example programs for libsc. For the C++ API, the examples are located in *authoring/libsc/examples*.

For the Java API, the Java source files are located in *authoring/libsc/java/examples*.

The examples cover a variety of topics, including setting up clip regions, creating geometry, adding textures and materials, vector culling, and working with text. Below are instructions for building and running the libsc examples.


C++ examples
------------

In addition to the example code, project files are provided which allow the examples to be compiled into a single executable. Individual examples can be executed by invoking the example executable with the name of a example and an output directory. The list of all available examples can be viewed by running the executable with no parameters.


Building and running the C++ examples on Windows
------------------------------------------------

On Windows, solution and project files are provided for Visual Studio. By default, the project is configured to run a basic example and output the result to the *authoring_samples_data* folder in the *quick_start/content* directory. The example that will be executed and the output directory can be configured by modifying the Command Arguments property of the Debugging section of the project's properties in Visual Studio.

Alternatively, the examples can be run from the command line in the Windows Command Prompt. The following command line will run the *SC_Store_Text* example::

	authoring_samples sc_store_text C:/path/to/output/folder

	
Building and running the C++ examples on Linux
----------------------------------------------

On Linux, a makefile is provided which will build the example application simply by running make from the *authoring/libsc/examples* directory. The Linux example project does not include any default values, so the name and output directory must be specified on each invocation of the executable.

The following command line will run the *SC_Store_Text* example from a Linux terminal::
	
	cd authoring/libsc/examples

	### Run make to compile the examples
	make

	### Create an empty model directory
	mkdir modeldir

	### Run a sample -- in this case, we'll run the SC_Store_Text program
	authoring_samples sc_store_text /path/to/output/folder


Java examples
-------------

These examples illustrate how to author models from Java programs running on Windows and Linux. All examples depend on *scj.jar* and the sc_java shared library for your platform.

The *SCStoreUtilsText* example, which illustrates how to insert text as geometry, has additional dependencies consisting of: *scj_utils_text.jar* as well as the *sc_java_utils_text* and *hps_core* shared libraries for your platform. These additional dependencies are only required if you need to generate geometry for text strings.

A license is included in the *ScLicense.java* file for **evaluation use only**.


Running the Java examples on Windows
------------------------------------

To run a example on Windows, open up a command window, navigate to the *authoring/libsc/java* directory. Then copy the Java sample files, *sc_java.dll*, and *scj.jar* to a new working directory, where you'll compile the samples and dependencies together. (You must have the `Java Development Kit <https://www.oracle.com/technetwork/java/javase/downloads/index.html>`_ installed and available in your path to run the compilation.)

After compilation, create an empty directory to store your Stream Cache model. Finally, run the example with *scj.jar* in your classpath and the model directory as a parameter.

Here are the Windows commands:

.. code-block:: none

	cd authoring\libsc\java

	mkdir rundir
	copy /y examples\*.java rundir
	copy /y bin\Release_&lt;platform&gt;\sc_java.dll rundir
	copy /y scj.jar rundir

	### To compile and run the Text example, copy additional dependencies into place
	copy /y bin\Release_&lt;platform&gt;\sc_java_utils_text.dll rundir
	copy /y ..\..\converter\bin\&lt;platform&gt;\hps_core.dll rundir
	copy /y scj_utils_text.jar rundir

	cd rundir

	### Compile the examples
	javac -cp ".;scj.jar;scj_utils_text.jar" *.java

	### Create an empty model directory
	mkdir modeldir

	### Run Java examples
	java -cp ".;scj.jar" ScStoreCubeSample modeldir
	java -cp ".;scj.jar;scj_utils_text.jar" SCStoreUtilsText modeldir

	
Running the Java examples on Linux
----------------------------------

To run an example on Linux, open up a terminal window, navigate to the *authoring/libsc/java* directory. Then copy the Java example files, the sc_java shared object, and the *scj.jar* file to a new working directory, where you'll compile the samples and dependencies together. (You must have the `Java Development Kit <https://www.oracle.com/technetwork/java/javase/downloads/index.html>`_ installed and available in your path to run the compilation.)

After compilation, create an empty directory to store your Stream Cache model and set the ``LD_LIBRARY_PATH`` environment variable (this tells Java where to find libraries to load). Finally, run the example with *scj.jar* in your classpath and the model directory as a parameter.

Here are the Linux commands:

.. code-block:: none

	cd authoring/libsc/java

	mkdir rundir
	cp -f examples/*.java rundir
	cp -f bin/linux/libsc_java.so rundir
	cp -f scj.jar rundir

	### To compile and run the Text sample, copy additional dependencies into place
	cp -f bin/linux/libsc_java_utils_text.so rundir
	cp -f ../bin/linux64/libhps_core.so rundir
	cp -f scj_utils_text.jar rundir

	cd rundir

	### Compile the samples
	javac -cp ".:scj.jar:scj_utils_text.jar" *.java

	### Create an empty model directory
	mkdir modeldir

	### Set the LoadLibrary environment variable
	export LD_LIBRARY_PATH='.'

	### Run Java examples
	java -cp ".:scj.jar" ScStoreCubeSample modeldir
	java -cp ".:scj.jar:scj_utils_text.jar" SCStoreUtilsText modeldir


Viewing the model in a browser
------------------------------

To view your newly authored model, copy "modeldir" to *quick_start/content/model_data* in the Communicator package. Then, navigate to the *quickstart* directory and run *start_server.sh* (or *start_server.bat* on Windows) to start the local server.

Finally, in a browser, navigate to the following URL, setting the "instance" variable in the querystring to the name of your model directory:

``http://localhost:11180/hoops_web_viewer_sample.html?viewer=csr&instance=modeldir``
