Alias OpenRender Installation Notes

 These notes describe:

  1. How to configure a user account for using OpenRender

  2. How to test the installation of OpenRender

  3. Notes on this release.

Alias OpenRender Requirements

 You must be running IRIX 5.3 or 6.2 to use Alias OpenRender 8.0. To determine your version of IRIX, type:

uname -r

If you do not see the numbers "5.3" or "6.2" in the response, you do not have an appropriate version of IRIX installed on your machine. Please contact your local SGI representative for an upgrade.

Note: On SGI R5000, R8000, or R10000 series machines, you must render with one of the .5k renderers. On an SGI R4000 series machine, you must render with one of the .4k renderers. In both cases, the Makefile should be edited to reflect the type of machine you are running on.

The Alias OpenRender software is installed as part of the 8.0 Alias software installation. The software is installed in /usr/aw/alias/ODS/OpenRender. If you have not installed the software in /usr/aw/alias, replace all references to /usr/aw/alias with the appropriate directory for your machine.

To use Alias OpenRender copy the software from /usr/alias to your local directory. For example:

cd $HOME
mkdir openrender
cd openrender
cp -r /usr/alias/ODS/OpenRender .

Under IRIX 5 and later versions of IRIX, the whole process of dynamic loading has been simplified. This means that linking code with OpenRender is simpler. Below is a Makefile for building the examples under IRIX 5.

The most significant change is to the .c.o rule. In this rule is the statement

ld -shared $*.o -o $*.so

that converts object files to Dynamic Shared Objects (DSO) used by the renderer. If the renderer can't determine where the DSOs are located, you may have to set the environment variable LD_LIBRARY_PATH to the location of the DSOs.

OCR_OBJ=SChecker.o \
rainbow_light.o\
gs_light.o\
gs_shader.o

all: $(OCR_OBJ)

CFLAGS=-G 0 #irix

LDFLAGS=-lm #irix

.c.o:
cc $(CFLAGS) -c -I. -I.. -I$(ALIAS_LOCATION)/include $*.c
ld -shared $*.o -o $*.so
rm $*.o
mv $*.so $*.o
test: ./pix testS testbow testgs
echo 'Renderer Test Successful'
testgs: gs_light.o gs_shader.o
renderer $(ALIAS_LOCATION)/sdl/gs_trims0.125
echo
testbow: rainbow_light.o
renderer $(ALIAS_LOCATION)/sdl/rainbow

testS: SChecker.o
renderer $(ALIAS_LOCATION)/sdl/SChecker
./pix:
mkdir ./pix
clean:
rm -f $(OCR_OBJ) pix/BALL.SChecker "ocra*"

Testing OpenRender using the supplied samples

Step 1. Copying the supplied samples to the user's account

 Log in as the user for whom you configured the system. Make a directory in which to test the renderer:

mkdir ocr <CR>

You can also create the ocr directory in user_data/<project>/.

Change into the directory :

cd ocr <CR>

Copy the supplied sample files :

cp /usr/aw/alias/ocr/samples/* .

Execute a test on the copied files to ensure that the renderer is correctly installed :

make test

If you do not see the message :

Render Test Successful

then retrace the above instructions to make sure that you performed all of them correctly. If your problem persists, please fax us a description of your problem.

Alias Supplied Sample Code

Examine the samples in the sample directory (/usr/aw/alias/ODS/OpenRender/samples). Each example has a file with a .README suffix which explains the purpose of the example.

To try out one of the examples, check each .README file to determine which files from the directory constitute the given example.

Copy the files listed in the example's .README to a test directory. With the exception of Tfizzle, all the examples use the same makefile. For Tfizzle, follow the steps outlined in the Tfizzle.README file.

For examples other than Tfizzle, type :

make <example>.o

where example is the name of the specific example (for example, SChecker, rainbow). This invokes the compiler and creates a .o file for the renderer to load.

While the example will prove to be useful in understanding the rendering process, it may be easier to use the Alias-supplied templates as a starting point for your own development.

Three template files (simple_light.c, simple_shader.c, simple_texture.c) are provided in the templates directory. Use the makefile supplied in the samples directory to create your own modules.

SDL Path Variable

ALIAS_OCRPATH - The "create" SDL statement requires a "filename" component, which indicates which .o file should be dynamically loaded. It may be inconvenient to fully qualify the path name of the capsule in which case the renderer will search $ALIAS_OCRPATH for the .o. For example:

If you have produced /u/joe/mylight.o you might use the following SDL:

create light (model=mylight, filename="/u/joe/ mylight.o");

or you can type into csh :

setenv ALIAS_OCRPATH /u/joe/

and then use the following statement in the SDL:

create light(model=mylight, filename="mylight.o");

Extraneous Files created

If, for some reason, the renderer exits prematurely, it may leave a file in your current working directory with a name like ocra0012. This file can simply be deleted. Do not delete this file while OpenRender is running; it should be automatically deleted once the rendering process has finished.

V5.1.1 Changes to OpenRender

In V5.1.1, two new fields were added to the data structure "AR_TextureData" for texture mapping. They are:

float TDblurmult;
float TDbluroffset;

Previously, all the information about blurmult and bluroffset were assigned to and read from the "AR_TextureInfo" structure (fields were named "blurmult" and "bluroffset"). The change now implies that new texture plugins require that the blurring values are placed and read from the AR_TextureData blur fields instead of the AR_TextureInfo blur fields.

In your actual texturing code, if you previously had:

int CALC (AR_TextureData *texture)

{

blurmult = texture->TDdata->blurmult;
bluroffset = texture->TDdata->bluroffset:

}

It should now be:

int CALC (AR_TextureData *texture)
{

blurmult = texture->TDblurmult;
bluroffset = texture->TDbluroffset;

}

V6.0 Changes to OpenRender

In V6.0, there are several new fields in the data structure "AR_LightData" for lights. They are

AR_Boolean computed_cosln;
float cosln;
AR_Boolean force;

The computed_cosln and cosln fields are for optimization purposes only. The light computation may do a dot product between the light vector and the surface normal. If so, then this step can be avoided in the shading step. The dot product is stored in the cosln field, and if this dot product has been stored in cosln, then computed_cosln is set to TRUE. Note that computed_cosln must be set to FALSE before the call to the light->calc() routine. An example of how this optimization should be used is in the simple_shader.c example supplied on the CD.

The force boolean is used to allow the light to inform the shader if it is a force. This flag should be set to FALSE before the call to the light->calc() routine. Failure to do so may result in your shader returning no color at all.

There are four new fields in AR_ShadeData. They are meant for the rendering of "shadow catchers". By a shadow catcher, we mean that the shading for the surface is ignored and the background color is used instead, with only shadowing and reflection accounted for. This allows the user to place fake objects that catch shadows and reflections in order to blend Computer Graphics objects with live action plates and backgrounds. The four parameters are:

AR_Boolean background_colour;
AR_Rgba matte_light;
AR_Rgba matte_shadow;
AR_Rgba matte_reflection;

The background_colour field indicates whether the current shader is a shadow catcher. If FALSE, then the remaining three fields are irrelevant. Otherwise, matte_light is the total light intensity collected for this shader, matte_shadow is the total shadow occlusion fraction (out of the total matte_light intensity), and matte_reflection is the mirror reflection result. Then the shading is done as follows:

shading result = matte_shadow / matte_light * background +
matte_reflection

Technical Help

Support is available through the Assist Hotline at a reasonable cost; Alias Assist has a full-time programmer on staff dedicated to OpenModel/OpenAlias. This person is an experienced C/C++ programmer and is in daily contact with the R+D team responsible for the API. Because of the specialized nature of the support requirements of an API, this is charged separately from regular maintenance at a reasonable cost.

The support provided includes answering questions on the use of the interface routines and their calling parameters, include files and libraries. You will be able to get help understanding Alias defined data structures and types, and advice on the correct approach to the problem you're trying to solve given our knowledge of the inherent capabilities of OpenModel/OpenAlias. We will also be able to explain the source code examples provided so that you have a full understanding of what you are building on.

Please note however that OpenModel/OpenAlias support through Assist is not a general consultation service to help debug non-API related problems, such as algorithms or NURBS math.

Alias Assist

VOICE (416) 362-8670

FAX (416) 362-1276

Introduction

ALIAS OpenRender lets you write custom C code modules for lights, shaders and textures. These custom modules can then be linked into the Alias Rendering products through statements in Alias SDL (Scene Description Language) files. To give you a full range of functionality (functionality equal to any of the Alias predefined lights, shaders and textures), the format of the ALIAS OpenRender C code modules that you write must follow certain guidelines.

The flow of the renderer is not changed for ALIAS OpenRender. When the renderer encounters a user-defined shader, light, or texture, control is passed to the ALIAS OpenRender function you've created. These functions process the data passed to them, then return control to the Alias renderer.

Since much of what must be written for an ALIAS OpenRender code module is repetitive, we have provided you with several simple examples that you can copy and modify for each shader, light, or texture that you write. These templates define six of the nine functions required for each ALIAS OpenRender C code module. You must write the three remaining functions and two data structures. The two data structures allow you to extend the syntax of SDL inside of your new shader, light, or texture. The fields that you add to your data structures can be bound to new SDL keywords that you create, and the Alias Renderer automatically parses (reads from the file) and evaluates (determines their values) for you.

This document gives you:

  1. Write an ALIAS OpenRender C Code Module by modifying an ALIAS OpenRender Template File.

  2. Compile the ALIAS OpenRender C Code Module using the supplied Makefile.

  3. Modify the SDL to be rendered so that it uses the new ALIAS OpenRender module.

  4. Execute the renderer on the modified SDL file. However, before you program an ALIAS OpenRender module, it is important to understand the steps involved in the Alias rendering process.



[email protected]
Copyright ©1998, Alias|Wavefront, a Silicon Graphics Company. All rights reserved.