Shout3D™ 2.5 - User Guide

Embedding Shout3D Applets in Web Pages

Attributes
Parameters

Shout3D applets are embedded in HTML pages in the same way that all kinds of applets are – with <APPLET> tags. <APPLET> tags contain all of the information necessary to allow a Java Virtual Machine to run an applet within the space of a Web page.

The default Shout3DApplet, and hence all other applets you can create with Shout3D, have 3 keyboard key controls. Click in the applet and then press the 'f' key to toggle a display of the frame rate. Press the 'h' key to toggle between hardware and software rendering. Or press the 'c' key to print a polygon count to the Java Console. Each of these key controls can be disabled by setting the values of applet parameters to false. See the information in the parameters section below for more information.

The Shout3D Wizard automates the creation of <APPLET> tags. However, it's important to have a basic understanding of these tags, as you will often find it necessary or convenient to create (or edit) them by hand.

The best way to become introduced to the use of <APPLET> tags in Shout3D is to follow the Wizard QuickStart Tutorial.

Information in an <APPLET> tag is divided into attributes and parameters. The attributes define features common to all Java applets, and are listed within the opening <APPLET> tag itself. Parameters define features that are specific to a given applet, and Shout3D applets have parameters that are unique to them. Parameters are listed between the opening and closing tags (<APPLET> . . . </APPLET>).

Attributes

CODEBASE specifies the location of the codebase directory relative to the location of the HTML file that contains the applet tag. In other words, it's the path from the HTML file to the codebase. The codebase is the directory that contains all the Java class files and media assets used by the applet. The CODEBASE attribute is the one you are most likely to need to edit when preparing the HTML file for uploading to a Web server.
CODE specifies the location of the applet class file you are using, relative to the codebase directory. This attribute might specify the location of the default Shout3DApplet.class, or of custom applet class files such as ExamineApplet.class or WalkApplet.class
ARCHIVE specifies the location of a packaged bundle of files, which in the case of Shout3D is always a .zip file. The use of archives speeds downloading by delivering many classes in a single transaction. By default, the archive will be shout3dClasses.zip, which contains a selection of class files that are used by most applets. However, you can create a custom optimized archive using the Shout3D Wizard that will provide only the precise classes required for your specific scene and applet.
WIDTH and HEIGHT specify the dimensions of the applet window. These values can be stated in pixels or as a percentage of the dimensions of the browser window.
NAME assigns a unique identifier to the applet in the HTML page. This attribute is only necessary where the applet is addressed by JavaScript code in the HTML page.
MAYSCRIPT is a single-word attribute that is required for applets that employ javascript code in the HTML page.

The attributes of a typical Shout3D <APPLET> tag might look like this:

<APPLET CODEBASE="../codebase"
CODE="shout3d/Shout3DApplet.class"
ARCHIVE="shout3dClasses.zip" WIDTH=320
HEIGHT=240>

Parameters

Parameters are unique to a given applet. An applet must be designed to accept parameters, and if it is, it will consult the <APPLET> tag to see if any have been provided. If a parameter is specified in the <APPLET> tag, its value will be used by the applet. If a given parameter is not specified, the applet will use a default value.

The Shout3DApplet (and therefore all applets extended from Shout3DApplet) accepts the following parameters. Where any of these are not specified, the default value indicated will be used. All files passed as parameters are relative to the directory specified in the CODEBASE attribute.

"src" specifies the .s3d, .s3z or .wrl scene file to be loaded by the applet. The src parameter is the only one that must be specified in every case as there can be no default value.
"background" specifies the location of a .gif or .jpg image file to be used as a backdrop. If this parameter is specified, it will override any Background node in the scene file as the starting background.
"backgroundColorR" , " backgroundColorG" and " backgroundColorB" specifies the RGB color of a solid color backdrop. This parameter will override any Background node in the scene file as the starting background. In absence of any background parameter or Background node, the default background is black.
"backgroundStretchToFit" sets the value of the Background node's stretchToFit field to true or false. The default value is false.
"headlightOn" can be set to true to create a headlight for the scene. Technically, this parameter overrides the headlight field of a NavigationInfo node in the scene file. As scenes exported using the MAX Export Plugin and many VRML exporters will not have a NavigationInfo node unless one is deliberately created, the default is effectively false (i.e., if the parameter is missing, there will be no headlight).
"antiAliasingEnabled", if set to true, will perform antialiasing at the edges between scene geometry and the background. This improves image quality at some cost in performance. The default value is false.
"bilinearFiltering" smoothes out the pixilated artifact that occurs when small textures are applied to large surfaces, at some cost in performance. The default value is true.
"loadResourcesInSeparateThread" allows resources (such as bitmaps and sound files) to load independently of the scene file. The scene appears at quickly as possible, but geometry will appear "naked" before its textures load. If this parameter is set to false, the resources load in the same thread as the scene. This may take longer, but nothing will appear "naked." The default value is true.
"nodeSearchPath" allows you to change or add to the default directory locations where the Shout3D viewer will look for node class files. This lets you store custom nodes in locations other that the standard custom_nodes directory. If this parameter is not specified, the default search path is used. The use of node search paths is discussed elsewhere in this User Guide.
"panelAutoFillsApplet", if set to true, will cause the 3D viewing window (the panel) to adjust to fill the size of the applet. If the applet's WIDTH and HEIGHT attributes have been defined as percentages of the browser window, the applet will resize as the user resizes the browser. If the panelAutoFillsApplet parameter is set to true, the 3D viewing window will also resize to fill the current size of the applet. The default value of this parameter is false.
"renderer", by default, specifies the Shout3D Java software renderer ("s3d"). Change the value to "OGL" to indicate that OpenGL hardware acceleration should be used, if possible.
"pixelDoubling" is off by default. You can set this parameter to one of four values.
1. "false" means no pixel doubling
2. "regular" means regular pixel doubling
3. "smooth" means smooth pixel doubling
4. "true" means regular pixel doubling (same as "regular")
"regcode" and "regname" parameters provide the registration information necessary to remove the logo strip from the bottom of the applet.
"frameCounterEnabled" defaults to true. Set it to false and clicking the 'f' key in the applet window will not toggle a display of the frame rate.
"polygonCounterEnabled" defaults to true. Set it to false and clicking the 'c' key in the applet window will not cause a polygon count to print to the java console.
"hardwareToggleEnabled" defaults to true. Set it to false and clicking the 'h' key in the applet window will not the applet to toggle between hardware and software rendering.