The first step in setting up a demo is to collect the entire demo into a directory (subdirectories are fine, but all the data, executables, etc. are located in a specific directory or in subdirectories of it).
This directory should be placed within the demo directory structure - the naming convention (convenient, not required by Portalis) is to locate these demo directories according to author. So demos written by ASD within SGI go into /usr/demos/HighEnd/sgi/ASD... Demos written by partners go in the partner's named directory in /usr/demos/HighEnd/partners...
This directory is also the location for Portalis configuration files. In this top demo directory the first step is to make a .portalis file. For a fully complete sample (including many advanced features) see this fully documented example, but for most demos following the directions below should be sufficient.
First off - a line can be commented by placing a # (pound sign or hash mark) at the beginning of the line.
# lines like this are totally ignored...
The demo name is just that - the name of the demo - in plain text. But in order to fit on the portal in portalis the name can be a maximum of 20 characters (including spaces and other symbols).
name: My Cool Demo
Next is how to run the demo - a script name to execute. This does not allow any command line arguments.
launch: RUN
And the last required part of a .portalis file is the category or categories that this demo fits into. There are quite a few ways to categorize a demo: who wrote it, what markets it fits into, what (software) features it takes advantage of, and what hardware it takes advantage of. Categories can be nested by using / as a separator. For a list of different categories see /usr/demos/Demo_Interfaces/Portalis/misc/categoryconfig.info (the second name in each listed category is the Portalis listing, the first is a filename variation of the name with no spaces or other special characters).
category: My Demos category: InfiniteReality/Features/Open GL category: InfiniteReality/Hardware/Hardware Texturing
You now have a legal and useful .portalis file:
name: My Cool Demo launch: RUN category: My Demos category: InfiniteReality/Features/Open GL category: InfiniteReality/Hardware/Hardware Texturing
The next step is to create this RUN script. Portalis can help you out by creating a stub script based on the .portalis file (this becomes much more useful as the .portalis files get more complicated). From the demo directory type:
/usr/demos/Demo_Interfaces/Portalis/bin/portalis -master -makeRUN
This will create a file called RUN.stub with regions marked by:
#### ADD CODE HERE
where you should put all the needed stuff to run the demo,
Once this is done you should be able to run Portalis in the normal way and have your new demo show up and run when clicked.
Given a simple .portalis file like the one above, there are some additional features that add quite a bit in terms of usability of a demo...
This specifies a script to abort the demo. This is most useful to the user who accidentally starts up a slow loading demo and wants to abort it before the demo is accepting a quit command. The -makeRUN comment given above to make the stub RUN script will also make a sub STOP script if an abort tag is given in the .portalis file. For example:
abort: STOP
Adding a icon for the demo means the portal for the demo can have a picture of the demo instead of the default icon. To make an icon file you need an image in .sgi format (for example you can use the scrsave command while running the demo). This image needs to be converted to a .256 file to be read by Portalis. There is a program (ezra) in the bin directory that will convert any sized .sgi or .rgb file to .256 file. However ezra will not convert images with alpha information. If you have an image with alpha information use imgcopy to make an image without alpha information.
From the demo directory type (with the appropriate names):
/usr/demos/Demo_Interfaces/Portalis/bin/ezra demoname.sgi demoname.256
Then in the .portalis file you can enter a line like:
icon: demoname.256
This gives the ability to bring up help on the demo from within Portalis. Netscape is used to display this file, so it should be a .html file.
For example:
documentation: demoname.html
There is a script called makeINDEX that makes a stub .html file based on the .index file (not the .portalis file). For more information on .index files see example.index or example.index.empty.
From the demo directory type:
/usr/demos/Demo_Interfaces/Portalis/bin/makeINDEX
This will create a file with the .html.STUB extension. This file will reference images that can be converted from the same snapshot used to produce the .256 file...
/usr/demos/Demo_Interfaces/Portalis/bin/webpix demoname.sgi
You can also change the icon on category portals - you need to specify the name of the category, so if the image does not show up when you expect it to check closely the spelling...
For example:
cicon: My Demos coolimage.256
Portalis descends the demo directory tree looking for .portalis files. However in order to speed up this process any directories containing a .portalis file are not descended any further into.
Portalis supports any number of demos within one .portalis file. The file is parsed in order - a new "demo" is indicated by the name: tag. And all tags until the next name: tag apply to this demo. The category: tag(s) should be the last entries for a given demo (tags after one category tag but before another may only affect the later category entry).
Portalis has some powerful mechanisms for selection configuration options for demos. As part of this there is support for auto-detection of hardware features, and Portalis level system configuration (rather than per-demo). For example if a demo can run with a single graphics pipe or with three, Portalis can be configured to prompt the user which version to run. However Portalis will not let a single pipe user run the three pipe version. Portalis will also remember how the user ran the demo last time...
option: pipes single option: pipes triple
This tells Portalis that this demo supports single or triple pipe and that the RUN script can handle these options. This is where making a stub RUN script is more useful. Portalis will make the stub RUN script with configuration sections so code specific to the single or triple pipe version gets run according to what the user has chosen. There are also parameters - in this case what is the order of the pipes (in triple pipe mode) from left to right? Portalis handles all this, and the RUN script just has to use the appropriate environment variables - in this case _pipeL, _pipeM, _pipeR.
Given only one option of a type (like pipes) gives information what the demo supports, but means the user will not be given any choices of that type.
A demo can also have requirements for the demo. For example how much memory the system needs to have:
need: mb_memory 512
Portalis will not allow the demo to be run if all the needs given in the .portalis file are not met.
For lists of needs, options and the environment variables to use for configuration information see /usr/demos/Demo_Interfaces/Portalis/misc/optionconfig.info.
launch: is the normal usage however if for some reason Portalis is suspected of causing frames to be dropped try waitlaunch: - this causes Portalis to totally suspend until the demo quits. Normally Portalis just sleeps when the mouse is out of the window and spends minimal CPU time checking if the mouse is back in the window. No drawing is done during this check, however waitlaunch: is much more extreme and prevents even this checking from happening...
launch: RUN waitlaunch: RUN
Not only can you give category icons for the portal, you can specify the textures for the entire room! For defaults and other information see /usr/Demo_Interfaces/Portalis/misc/images/.portalis.
The clouds or whatever flowing "outside" the dome/sphere.
dometex: Help green.marble.2.256
The lattice structure of the dome/sphere.
structex: Help redmar256.256
The material the outside of the portal is made of.
portaltex: Help terra.cotta.256
The material the back of the portal is made of.
portalbacktex: Help HighEnd_sgi.256
The center part of the platform in the center of the sphere.
platformtex: Help brick256.2.256
The border around the platform.
platformbordertex: Help marble.5.256
The walkway leading to the portals.
wwaytex: Help clouds256.256
There is a script called makedist that uses the .index file to make and inst image. It is currently set up to build with -sbase /demobuild and -dist /demobuild/dist. [This means that the directory tree is under /demobuild/usr/demos/... and the images get placed in /demobuild/dist.] This script handles version numbers automatically.
From the demo directory type:
/usr/demos/Demo_Interfaces/Portalis/bin/makedist
New categories can be added just by using them in a .portalis file. However new Author or Feature pr Hardware or Market categories should be added into /usr/demos/Demo_Interfaces/Portalis/misc/categoryconfig.info.
New options can be entered into /usr/demos/Demo_Interfaces/Portalis/misc/optionconfig.info.
For example lets say a demo supports an additional movement device - a different serial joystick that Portalis doesn't currently know about. First add this line to optionconfig.info:
option: movement joystick "Joystick" "port" /dev/ttyd2 _joystick_port
Then add this line to the demo .portalis file:
option: movement joystick
Then generate a RUN.stub based on the changed .portalis file:
/usr/demos/Demo_Interfaces/Portalis/bin/portalis -master -makeRUN
Then just modify the appropriate sections in the RUN script to get the demo to use the joystick (with the parameter variable _joystick_port).
One reason the previous example is so simple is that there is no real way to auto-detect this joystick. New options that can be auto-detected and new needs need to be entered into both /usr/demos/Demo_Interfaces/Portalis/misc/optionconfig.info and /usr/demos/Demo_Interfaces/Portalis/bin/CHECK
For example adding another pipe option - two pipes. The line to be added to optionconfig.info is:
option: pipes double "Two Pipe" "Order (L,R)" 0,1 _pipeL,_pipeR
Now .portalis files can have a line like:
option: pipe double
RUN scripts can use the _pipeL and _pipeR parameter variables, etc.
But the auto-detection code in CHECK needs to be modified to understand this new option. There is a Perl subroutine called legal_config that does checking on options based on hardware information (gotten in the subroutine get_hardware_inventory). The hardware information subroutine already counts the number of pipes (the number is stored in the variable _num_pipes) so all that is needed is to modify legal_config to support the new double pipe option. What is needed is to insert the following code segment before the "triple" elsif :
elsif ($mem eq "double") {
if ($_num_pipes >= 2) {
return "yes";
}
else {
return "no";
}
} # double
This will make any system with two or more pipes return a yes when asked if double pipe is supported on this machine.
Comments so far:
HighEnd_Demos@sgi.com