OpenRender: The Alias

Rendering Library
© 1999, 2000 Alias|Wavefront
OpenRender: The Alias Rendering Library
© 1999, 2000 Alias|Wavefront

Documentation Team: Mona Albano, Pat Anderson, Matt Chaput, Stephen Gaebel, Karen Hoogsteen,
Adam Kozyniak, Joanne MacPhail, Margot Meijer.

Title page image © 1998 Shane Clodd

The following are trademarks of Alias|Wavefront, a division of Silicon Graphics Limited:

Alias MetaMorph MotionSampler OpenAlias

OpenModel OpenRender PowerCaster PowerTracer

QuickRender QuickShade QuickWire SDL

ShapeShifter StudioPaint RayCasting RayTracing

The following are trademarks of Alias|Wavefront Inc.:

3Design Advanced Paint Advanced Visualizer Composer

Data Visualizer Dynamation Explore Kinemation

VisPaint2D Visualizer Server

All other product names mentioned are trademarks or registered trademarks of their respective holders.

All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or
transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, or
disclosed to a third party, without the prior written permission of Alias|Wavefront. Information in this
document is subject to change without notice and does not represent a commitment on the part of
Alias|Wavefront or its employees or a complete and accurate specification of the product. While every
attempt is made to ensure the accuracy and completeness of the information in this document, some errors
may exist. Alias|Wavefront cannot accept responsibility of any kind for incidental or consequential
damages resulting from the use of this material or liable for technical or editorial omissions made herein.

Not all features described are available in all products. Printed in the USA by R.R. Donnelley.

Global European Asia-Pacific

Internet
Headquarters Headquarters Headquarters
210 King St. E. Handelsdokcenter, 5F 313 Minami-aoyama Bldg. http://www.aw.sgi.com
Toronto, Ontario Stapelplein 70, 3-13-18 Minami-aoyama [email protected]
Canada M5A 1J7 9000 Gent, Belgium Minato-ku, Tokyo 107
Tel 416 362-9181 Tel 32 9 266 1212 Japan
Fax 416 369-6140 Fax 32 9 266 1210 Tel 81 3 3470 8282
Fax 81 3 3470 8288
 —

About this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Alias OpenRender Installation Notes . . . . . . . . . . . . . . . . . . . . . . . 2

OpenRender Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Testing OpenRender using the supplied samples . . . . . . . . . . . . . . . . . . . . . . . . 3
Alias-supplied Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
SDL Path Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Version 8.5 Changes to OpenRender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Version 6.0 Changes to OpenRender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Version 5.1.1 Changes to OpenRender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Overview—The Alias Rendering Process . . . . . . . . . . . . . . . . . . . 9

Parse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Evaluate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Calculate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

The Application Program Interface (API) . . . . . . . . . . . . . . . . . . . 18

INIT() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
FREE() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
CALC() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Tutorial—Changing the OpenRender Template . . . . . . . . . . . . . 28

Standard Alias Shader Data Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
AR_ShadeData Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Standard Alias Light Data Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Standard Alias Texture Data Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
AR_TextureData Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Standard SDL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Customizing the OpenRender Template File . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Modifying SDL files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Tutorial—The Scan Line Shader . . . . . . . . . . . . . . . . . . . . . . . . . . 44

The CALC Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
.............................................................. 45
The size of the Image. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Passing other data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

APPENDIX—Alias-defined API Functions . . . . . . . . . . . . . . . . . . 47

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Guide to Alias OpenModel3

—

4 Guide to Alias OpenModel

About this Manual

This manual describes the program interface that you see for Alias OpenRender.
This manual describes how the renderer works and what modules must be written
to add OpenRender code.

The extent of OpenRender for this software release is limited to Lights, Shaders and
Textures.

OpenRender runs only on SGI UNIX (IRIX) machines.

Guide to Alias OpenModel 1

Alias OpenRender Installation Notes — OpenRender Requirements

Alias OpenRender Installation Notes

These notes describe:

• How to configure a user account for using OpenRender

• How to test the installation of OpenRender
• Notes on this release.

OpenRender Requirements
You must be running IRIX 6.5.4 to use Alias OpenRender 8.0. To determine your
version of IRIX, type:

uname -r

If you do not see the number “6.5.4” in the response, you are not running the
appropriate version of IRIX. 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, edit the Makefile to reflect your
type of machine.

The Alias OpenRender software is installed with the Studio software, in

/usr/aw/alias/ODS/OpenRender. If you have not installed the Studio software
in /usr/aw/alias, installation replace all references to it with the directory that
you are using.

To use OpenRender, first copy it from /usr/aw/alias/ODS/OpenRender 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.

2 Guide to Alias OpenModel

 Alias OpenRender Installation Notes — Testing OpenRender using the supplied samples

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 find the DSOs, you may have to set the environment variable
LD_LIBRARY_PATH to their location.

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>/.

Guide to Alias OpenModel 3

Alias OpenRender Installation Notes — Alias-supplied Sample Code

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

4 Guide to Alias OpenModel

 Alias OpenRender Installation Notes — SDL Path Variable

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 searches
$ALIAS_OCRPATH for the .o file. 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 the renderer exits prematurely, it may leave a file in your current working directory
with a name like ocra0012. You can simply delete this file. However, do not delete it
while OpenRender is running; OpenRender should delete it when rendering has
finished.

Version 8.5 Changes to OpenRender

OpenRender plug-ins now work with the N32 compiler.

The renderers can now choose plug-ins compiled for different CPUs and created
with different compilers. If you compile your plug-in for a specific class of machine,
add one of the following suffixes:

• *.i5.4k — an O32 binary compiled for R4000 processors

• *.i6.4k — an N32 binary compiled for R4000 processors
• *.i6.5k — an N32 binary compiled for R5000 processors
The renderers search for the plug-in with the correct suffix. (there is no need to
specify the suffix in the SDL). If the renderer cannot find a plug-in with the correct
suffix it checks for a plug-in with no suffix (assuming that you did not specify a suffix
in the SDL).

Guide to Alias OpenModel 5

Alias OpenRender Installation Notes — Version 6.0 Changes to OpenRender

Version 6.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 only. The light
computation might 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

6 Guide to Alias OpenModel

 Alias OpenRender Installation Notes — Version 5.1.1 Changes to OpenRender

Version 5.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 plug-ins 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;
…
}

Introduction
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 Scene Description Language (SDL) files. For
functionality equal to any of the Alias predefined lights, shaders and textures, the
format of the OpenRender C code modules that you write must follow certain
guidelines.

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

Guide to Alias OpenModel 7

Alias OpenRender Installation Notes — Introduction

to them, then return control to the Alias renderer.

Since much OpenRender code 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
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 parses (reads from the file) and evaluates (determines their values) for
you.

This document does the following:

• gives you a broad overview of the Alias Rendering process,

• describes where the OpenRender C code modules fit in,
• then takes you through a step-by-step creation and modification of an
OpenRender C code module.
To add an OpenRender C Code Module to the Alias renderer, the process is as
follows:

1 Write an OpenRender C Code Module by modifying an OpenRender Template

File.
2 Compile the OpenRender C Code Module using the supplied Makefile.
3 Modify the SDL to be rendered so that it uses the new OpenRender module.
4 Execute the renderer on the modified SDL file.
However, before you program an OpenRender module, it is important to understand
the steps involved in the Alias rendering process.

8 Guide to Alias OpenModel

 Overview—The Alias Rendering Process — Introduction

Overview—The Alias Rendering Process

This describes terms used in this document.

Object spaceThe coordinates of an object before any transformation, rotation, or

scaling has been applied to it.

World spaceThe coordinates of an object after all transformation, rotation, or

scaling has been applied to it. This includes transformations to
properly place the object in front of the camera.

Prototype ....An outline of a C Code Module (or a data structure) that has locations
for a programmer to add customized C code (or data fields).

OpenRender Template File

.....................A file that contains a number of prototypes.

Application Program Interface

.....................A collection of routines we supply for you to use in the OpenRender

C code modules you write.

There are four basic steps involved in rendering each image from an SDL file:

• Parse (reading information from the file)

• Evaluate (determine value of expressions for the current frame)
• Initialize (set up any per frame variables)
• Calculate (determine the color of the pixels)
If more than one frame needs to be calculated for an SDL file (for an animation, for
example), the process is repeated (except Parse—see Storing Information for
Multiple Frames for details). The Alias Renderer uses three types of data structures.

• NODE structures—used at Parse and Evaluate time to store a representation of

the SDL file
• INFO structures—used at Evaluation, Initialization, and Calculation time, to
store the evaluated values from the SDL file
• DATA structures—used only at Calculation time for passing information
between shaders, textures and lights
The following diagram represents the Alias rendering process.

Guide to Alias OpenModel 9

Overview—The Alias Rendering Process — Parse

Parse Evaluate Initialize Calculate

NO

done
Node Info Data YES
Structure Structure Structure

Program flow and data structure usage

Parse
The renderer reads the SDL file once per render. At that time, the NODE structure is
created and initialized with a special kind of data structure, called an RR_ExpNode,
that can represent any type of data, including expressions, animation statements,
literals, variables, scalars, triples, and textures. All of the NODE structures are kept
together in an internal representation of the SDL file, which can then be evaluated.

SDL NODE data structure

shader shiny ( typedef struct NODE_TYPE {
model = my_ocr_shader, PARSE .
pattern = texture(...), ----> RR_ExpNode *pattern
. .
. .
. .
); } NODE_TYPE;

Evaluate
During the Evaluation phase, the NODE structure is evaluated into the INFO
structure; the current value of the variable is determined and placed into the INFO
structure. For example, if intensity is set to an expression:

light bright (
model = my_ocr_light_model,
intensity = (4.0*5.5)/3.2,

10 Guide to Alias OpenModel

 Overview—The Alias Rendering Process — Initialize

.
.
.
}

then the evaluation step takes the RR_ExpNode and evaluates the intensity of the
light to be 6.875. The following diagram shows the relationship between the NODE
and INFO data structures.

Created at Parse Time: Created at Evaluation Time:

typedef struct AR_LightNode { typedef struct AR_LightInfo
{
. .
. EVALUATION .
RR_ExpNode *color; ---------> AR_TextureType color;
. .
. .
} AR_LightNode; } AR_LightInfo;

Relationship between NODE and INFO data structures

The content of the RR_ExpNode structure is unimportant—OpenRender provides you

with a function to perform the evaluation for any type of RR_ExpNode, and if the
OpenRender Template File is used in the OpenRender C code module, this
evaluation is done automatically. In general, there should be one field in the NODE
structure for each field in the INFO structure, and the two fields should have the
same or similar names for the sake of clarity.

Initialize
The INFO structure can have additional fields (that are not in the NODE structure) to
store information that does not change during a frame, and so only needs to be set
once for that frame at initialization time. For example, with Alias lights, the Alias
defined INFO structure has an extra field called transformed_color, which is the
combination of the light’s intensity and the light’s color for the current frame.

pInfo->transformed_color.r = pInfo->color.out.r * pInfo-

>intensity;
pInfo->transformed_color.g = pInfo->color.out.g * pInfo-
>intensity;
pInfo->transformed_color.b = pInfo->color.out.b * pInfo-
>intensity;

Guide to Alias OpenModel 11

Overview—The Alias Rendering Process — Initialize

Similarly, if you have any texturable fields in one of your data structures, this is the
time to initialize them. For example, if your data structures look like:

#define NODE_TYPE myShaderNode #define INFO_TYPE myShaderInfo

typedef struct NODE_TYPE { typedef struct INFO_TYPE {
RR_ExpNode *pattern; AR_TextureType pattern;
.
.
.
.
} NODE_TYPE; } INFO_TYPE;

then your initialization routine should look like:

AR_Boolean INIT( INFO_TYPE *pInfo )

{
OCR_initialize_texture( pInfo->pattern.map );
.
.
.
return ( TRUE );
}

In many cases with your OpenRender C code modules, the initialize function can be
an empty function.

Forward Referencing Positional Information

If your OpenRender C code module uses a positional point variable (as the Alias
spot light does for the shine_along and up fields), then your INIT routine must do
some extra work to bind some variables together. This is to allow the positional
variables to be defined at any point in the SDL file.

To get around the problem of a possible forward reference, here is what Alias does
with spot lights. (Alias calls the variable shine_along even though it really is a
shine AT point. The direction of the spot light is calculated by subtracting the
shine_along point from the position of the light.)

The first thing to do is place a forward() statement around your possibly forward-
referenced field in the SDL file as shown below (to see exactly what the SDL looks
like, generate a small SDL file with a spot light in it and look at the layout—then try
grouping the spotview with another object, move and rotate that object and see

12 Guide to Alias OpenModel

 Overview—The Alias Rendering Process — Initialize

what the SDL looks like):

light spotlight#1 ( model = spot,

.
.
.
shine_along = forward( spotview#1 ),
.
.
.
);
.
.
.
MODEL
.
.
.
{
translate( 4.5, 9.8, 2.3 );
rotate( yaxis, 34.0 );
spotview#1 = current_position( 0.0, 0.0, 0.0 );
}
.
.
.
The forward() statement is added when you write out an SDL file from the Alias
interactive package. If you have a positional field in your OpenRender C code
module, you must add the forward() statement yourself by editing the SDL file.

Then, in the COPY routine, you must bind some variables together. Do this using
the OCR_bind_forward_reference() function so that the forward reference gets
carried over to all copies and instances of this light:

static long
OCR_Shallow_Copy(
INFO_TYPE *pTo,
INFO_TYPE *pFrom
){
pTo->field1= pFrom->field1;
pTo->field2= pFrom->field2;
pTo->field3= pFrom->field3;
.
.

Guide to Alias OpenModel 13

Overview—The Alias Rendering Process — Initialize

.
pTo->shineAlong.x= pFrom->shineAlong.x;
pTo->shineAlong.y= pFrom->shineAlong.y;
pTo->shineAlong.z= pFrom->shineAlong.z;
OCR_bind_forward_reference ( (AR_Triple*)(&(pTo->shineAlong)),
(AR_Triple*)(&(pFrom->shineAlong)) );
.
.
.
return (TRUE);
}

Then in the INIT routine, make sure that the variables are transformed properly into
eye space:

AR_Boolean
Ar_init_spot_light (
AR_SpotLightInfo *pInfo
)
{
.
.
.
OCR_transform_point( &(pInfo->shineAlong),
&(pInfo->transformed_shineAlong) );
.
.
.
return( TRUE );
}

Notice how to transform shineAlong into a different field in the INFO structure,
called transformed_shineAlong. It is important that the shineAlong field is
transformed into a different field so that multiple copies of the light are possible.
Results are unpredictable if shineAlong is changed by OCR_transform_point()
into shineAlong.

Be very careful. All forward reference fields must be triple variables. A triple literal
(that is, a line like shine_along = (0.0, 1.0, 3.0) in the spotlight definition)
does not work, even with a forward() statement around it.

14 Guide to Alias OpenModel

 Overview—The Alias Rendering Process — Initialize

Storing information for multiple frames

If you are initializing a field of your INFO structure on the first frame of an animation,
and just incrementally modifying it for each subsequent frame, be careful to modify
the OCR_Shallow_Copy() (in the OpenRender template) in your OpenRender C
code module so that it does not copy the fields that you want to keep from frame to
frame. (Lights are passed a new INFO structure each frame—do not count on being
able to store information in your light INFO structure for multiple frames. For this
reason, sub-allocations for lights are not recommended.)

For example on the first frame of an animation, you want to allocate an array of
values to be used and updated each frame. You only want to allocate the array
once on the first frame. You have defined a field in the INFO structure called
particle_array to store the array. Your INIT routine might do something like the
following:

AR_Boolean INIT( INFO_TYPE *pInfo )

{V
if (pInfo->particle_array == NULL) {
/* Allocate an array of 50 floats. */
pInfo->particle_array = OCR_allocate( sizeof(float) * 50 );
/* initialize particle_array here, somehow */
}
/* update particle_array here, somehow */
return(TRUE);
}

Here is what can go wrong with this type of arrangement:

If the above OpenRender module is used as a variable anywhere in an SDL file, the
field particle_array will be NULL each time the INIT routine is called. This is
because when a variable is assigned to a field of another object, a copy of the
variable is made. In this case, a copy of the INFO structure is placed in the field
assigned, and the copy is passed to your INIT routine. The same process is
repeated on all subsequent frames. You will be modifying the copy each time, but
the original INFO structure never gets updated, and the original structure is copied
over top of the copy each frame, and your sub allocated memory is lost. This is
because the OpenRender template uses a shallow copy routine (a copy routine that
has no knowledge of the underlying data structure).

If you want to keep the particle_array information in the INFO structure, change
the OCR_Shallow_Copy() routine so that the particle_array field is not copied:

Guide to Alias OpenModel 15

Overview—The Alias Rendering Process — Calculate

static long
OCR_Shallow_Copy(
INFO_TYPE *pTo,
INFO_TYPE *pFrom
){
pTo->field1= pFrom->field1;
pTo->field2= pFrom->field2;
pTo->field3= pFrom->field3;
/* pTo->particle_array = pFrom->particle_array; /* NO, we don't copy
this. */
return (TRUE);
}

Note: Lights are a special case, since they are treated like geometry—the INIT
routine is passed a new INFO structure each frame. Do not attempt to store
information in your light INFO structure between frames. The FREE routine
for your light must free any substructures you have allocated, and the COPY
routine for lights should copy the pointer to any sub allocation from the From
object to the To object, and then NULL out the From object’s pointer. This
must be done so that the memory is not freed twice by two separate calls to
your C module FREE routine. This should only concern you for lights.
Shaders and textures will not be freed during any render.

Calculate
The calculate routine:

• is the focus of the code module.

• is called for every pixel that is affected by the user-supplied shader, light or
texture.
• given some initial condition (for example, a point on a surface), performs a
calculation (for example, a color value).
Take great care when writing this function, since it can be called several million
times per frame. The calculate function, on successful completion, places the return
information in an Alias supplied DATA structure. For example, a light module might
calculate the illumination value to be added to the current point being shaded.
However, the means by which the intensity value is applied to the point depends on
the shader module. The DATA structure is used to pass information between the
lights and the various shaders. Since all lights put the same information into the
DATA structure, the shader modules can be independent of the type of light being
applied to a point. This rule applies to all combinations of lights, shaders and
textures. Each type of module (that is, light, shader and texture) uses a specific

16 Guide to Alias OpenModel

 Overview—The Alias Rendering Process — Free

DATA structure to pass information to other modules; these DATA structures have
room for user-defined extensions.

Free
In most cases, the free routine is a NULL function. Its purpose is not to free the
INFO structure itself, but to free any sub-structures that you may have allocated in
your INIT or CALC routines. For example, Alias spotlights allocate a depth map
array in order to do shadows, so their free routines look like:

AR_Boolean FREE( INFO_TYPE *pInfo )

{
if (pInfo->depth_map != NULL)
{
OCR_free( pInfo->depth_map );
pInfo->depth_map = NULL;
}
return( TRUE );
}

Guide to Alias OpenModel 17

The Application Program Interface (API) — INIT()

The Application Program Interface (API)

In this section, we describe both the Alias functions in your OpenRender module
and the format of user-defined functions. These functions as a group, along with the
format of calls to the OpenRender C code modules, are known as the Application
Program Interface (API). The OpenRender API also includes several C macros to
help you program OpenRender C code modules.

All user-defined functions must return TRUE on success and FALSE on failure.

Assuming that the OpenRender Template file is used, there are only three functions
to be written: INIT(), FREE(), and CALC().

The rest of this section assumes that the OpenRender Template is being modified
to create a new module. Writing an OpenRender C Code Module from scratch
should not be attempted without training.

In the prototype code outlined below, comments that appear in bold text are
locations where you should perform certain calculations, or insure that an Alias
AR_???Data structure gets updated with values.

All prototypes in this section should be available on-line under /usr/alias/ocr.

INIT()
static AR_Boolean INIT( INFO_TYPE *pInfo )—This function must return
TRUE on success and FALSE on failure. That initializes any variables in your INFO
structure that do not have a corresponding field in the SDL file. In most cases, this is
an empty function. Values that should be set in this function include:

• Any constant values in your INFO_TYPE structure that are not evaluated from
the NODE_TYPE.
• Any values based on a combination of NODE_TYPE fields.
• If your INFO_TYPE structure has a texturable field, it should be initialized here.

FREE()
static AR_Boolean FREE( INFO_TYPE *pInfo)—This function must return
TRUE. It frees any memory that has been allocated and placed into the INFO
structure so that the INFO structure itself can be freed.

18 Guide to Alias OpenModel

 The Application Program Interface (API) — CALC()

Note: This function should not attempt to free the INFO structure itself.

CALC()
There are three different prototypes for the CALC() routine, depending on the type of
module.

Shader
static int CALC (
AR_ShaderInfo *pShader,
AR_GeometryInfo*pGeometry,
AR_ShadeData *pShadeData,
AR_OCR_ObjectInfo*object_info,
void *ni,
void *rt_ray_rec
)

This function takes a given point to shade (specified in the AR_GeometryInfo

structure), walks through the light list (specified in the AR_ShadeData structure),
sums the intensities of the lights and adds the lights’ ambient and diffuse values,
factors in transparency, and adds the specular term to arrive at the final color for the
point (results are placed in the AR_ShadeData structure).

Before calling each light, the shader routine should set three flags to FALSE:
light_data.ambient, light_data.diffuse, and light_data.specular. These
three flags indicate what kind of contribution the current light makes to the point
being shaded, and they are set by each light routine. An ambient light only sets
light_data.ambient to TRUE; a point light sets light_data.diffuse and
light_data.specular to TRUE.

The specular component (if any) is applied according to the shading model the
shader implements. For example, the Lambert shading model does not implement a
specular component, so the specular portion is not factored into that shading
model’s results.

The AR_ShaderInfo structure points to your INFO structure from the

user_shader_info field. When accessing the INFO structure through this pointer,
the pointer should be cast to the INFO structure type. This function should always
return TRUE; it is not allowed to fail.

The last three arguments to this function are used strictly for raytracing and are
required to calculate the reflected ray color.

Guide to Alias OpenModel 19

The Application Program Interface (API) — CALC()

During the rendering phase, once you are shading a single ray, the order of calling
the CALC routines is: Textures, Shaders, Lights. Alias calls and calculates all
textures referenced in the standard Alias shader. The calculated values from the
textures are placed in AR_ShadeData and then passed to the shader CALC function.
If your Shader INFO structure contains any textures, you must call their CALC
functions at the start of your shader CALC function by setting up an
AR_TextureData structure and calling OCR_INVOKE_MAPPING(). Then your Shader
routine should walk the light list, calling each light in turn. Each light returns an
AR_LightData structure that contains the lighting contribution of the current light.

A Shader Prototype
int CALC (
AR_ShaderInfo *pShader,
AR_GeometryInfo *pGeometry,
AR_ShadeData *pShadeData,
AR_OCR_ObjectInfo *object_info,
void *ni,
void *rt_ray_rec
)
{
AR_Rgb ambient_term;
AR_Rgb diffuse_term;
AR_Rgb specular_term;
AR_Rgba result;
AR_Rgba rgba;
INFO_TYPE *pInfo;
AR_LightData light_data;
AR_LightInfo *pLight;
AR_LightList *pLL;
double diffuse_coeff;
double specular_coeff;

pInfo = (INFO_TYPE *) pShader->user_shader_info;

/* call OCR_INVOKE_MAPPING() for any texturable fields in your
structure */
ambient_term.r = ambient_term.g = ambient_term.b = 0.0;
diffuse_term.r = diffuse_term.g = diffuse_term.b = 0.0;
specular_term.r = specular_term.g = specular_term.b = 0.0;
for( pLL=pShadeData->lights; pLL!=NULL; pLL=pLL->next )
{
pLight = pLL->light;
if( !(pLight->active)) continue;
if( !(pLight->rtns->calc) ) continue;

20 Guide to Alias OpenModel

 The Application Program Interface (API) — CALC()

light_data.ambient = light_data.diffuse = light_data.specular

= FALSE;
light_data.user_data = NULL;
light_data.computed_cosln = light_data.force = FALSE;
if( !((pLight->rtns->calc)( pShadeData, &light_data, pLight )))
continue;
if( light_data.ambient )
{
ambient_term.r += light_data.intensity.r
* pShadeData->surfColor->r;
ambient_term.g += light_data.intensity.g
* pShadeData->surfColor->g;
ambient_term.b += light_data.intensity.b
* pShadeData->surfColor->b;
}
if( light_data.diffuse )
{
/* Calculate the diffuse contribution here and ADD results to
'diffuse_term'. */
}
if( light_data.specular ) {
/* Calculate the specular contribution here and ADD results to
'specular_term'. */
}
}
result.r = ambient_term.r + diffuse_term.r;
result.g = ambient_term.g + diffuse_term.g;
result.b = ambient_term.b + diffuse_term.b;
result.a = 255.0;
/* Calculate Transparency */
if ( pShadeData->surfTrans.r != 0.0 ||
pShadeData->surfTrans.g != 0.0 ||
pShadeData->surfTrans.b != 0.0)
{
/* The “transcol” is the color of the objects BEHIND the */
/* current surface. */
result.r +=pShadeData->surfTrans.r * (pShadeData->transcol->r -
result.r);
result.g +=pShadeData->surfTrans.g * (pShadeData->transcol->g -
result.g);
result.b +=pShadeData->surfTrans.b * (pShadeData->transcol->b -
result.b);
result.a +=pShadeData->surfTrans.a * (pShadeData->transcol->a -
result.a);
}

Guide to Alias OpenModel 21

The Application Program Interface (API) — CALC()

/* The specular term must be added after the transparency */

/* calculation or the specular will be incorrectly affected */
/* by the color of the objects behind the transparent surface. */
result.r += specular_term.r;
/* add the specular colour */
result.g += specular_term.g;
result.b += specular_term.b;
/* Add the surface incandescence. It is independent */
/* of the surf colour. */
/* THE SETTING OF pShadeData -> transcol MUST BE THE LAST THING DONE
BEFORE THE RETURN STATEMENT. */
pShadeData->transcol->r = result.r + pShadeData->incandescence.r;
pShadeData->transcol->g = result.g + pShadeData->incandescence.g;
pShadeData->transcol->b = result.b + pShadeData->incandescence.b;
pShadeData->transcol->a = result.a;
return (TRUE);
}

Light
static int CALC (
AR_ShadeData *pShadeData,
AR_LightData *pLightData,
AR_LightInfo *pLightInfo
)

This function is given a point to shade (specified in the AR_ShadeData structure)

and a light (specified by the AR_LightInfo structure). It then calculates the light’s
intensity at that point. The result is placed in the AR_LightData structure. If the light
contributes intensity to the point, TRUE is returned. If the light does not contribute
intensity to the point (for example, if the point is too far from the light source, or
shadowed from the light source), then FALSE is returned.

Your INFO structure is pointed to in the AR_LightInfo structure in the

user_light_info field. When accessing your INFO structure through this pointer,
the pointer should be cast to your INFO structure type.

Each light must set the pLightData->[ambient|diffuse|specular] flags

according to the type of contribution they make to the current point. If the light
makes a diffuse and/or a specular contribution, a normalized direction vector from
the point of intersection to the center of the light must be generated and placed into
AR_LightData. The pLightData->direction field is used in diffuse and specular
shading computations in the shader CALC function.

22 Guide to Alias OpenModel

 The Application Program Interface (API) — CALC()

A Light Prototype
int CALC (
AR_ShadeData *pShadeData,
AR_LightData *pLightData,
AR_LightInfo *pLightInfo
)
{
INFO_TYPE*Light_Info;
AR_ShadeData*hold_for_recursion;
floatintensity;
doublelength;
Light_Info = (INFO_TYPE *)pLightInfo->user_light_info;
if( !Light_Info ) return ( FALSE );
/* pLightData->direction MUST be set if either specular or diffuse */
/* are set to TRUE below. In this case, the light is hard coded to */
/* be at (32, 32, 32). */
pLightData->direction.x = 32.0 - pShadeData->crosspt->x;
pLightData->direction.y = 32.0 - pShadeData->crosspt->y;
pLightData->direction.z = 32.0 - pShadeData->crosspt->z;
OCR_NORMALIZE( length, pLightData->direction );
/* You must calculate the light's intensity into 'intensity' here. */
/* It should be a value >=0.0. */
if( intensity < 0.0001 ) return ( FALSE ); /* no contribution */
/* The following 3 flags MUST be set according to the type of
contribution */
/* this light can make to the point being shaded. */
pLightData->ambient= FALSE;
pLightData->diffuse= TRUE;
pLightData->specular= TRUE;
/* The final intensity of the light MUST be placed in pLightData-
>intensity. */
pLightData->intensity.r = pLightInfo->transformed_color.r *
intensity;
pLightData->intensity.g = pLightInfo->transformed_color.g *
intensity;
pLightData->intensity.b = pLightInfo->transformed_color.b *
intensity;
return ( TRUE );
}

Texture
static int CALC ( AR_TextureData *texture )—This function is given the
world space coordinates and parametric coordinates of a point (specified in the

Guide to Alias OpenModel 23

The Application Program Interface (API) — CALC()

AR_TextureData structure). It then calculates the color (including alpha channel) at

that point (results are placed in the AR_TextureData structure). Your INFO
structure is pointed to by texture->TDdata->user_texture_info. When
accessing your INFO structure through this pointer, the pointer should be cast to
your INFO structure type.

This function should always return TRUE upon success. If there is a problem, the
texture routine should return FALSE and it should not modify AR_TextureData-
>TDcolor, since the color has already been set to the texture’s out value.

NOTE: Textures require extra type specifications in the OpenRender C code

modules. When writing a texture, locate the #defines at the top of the file:

#define TEXTURE_STATUSFUNC_TEXTURE
#define TEXTURE_TYPE PARAMETRIC_MAP
#define TEXTURE_ABSOLUTEFALSE

If the defaults shown above are correct for the type of texture you are writing, then
no modification needs to be done. Here is what the three flags mean:
TEXTURE_STATUS can be FUNC_TEXTURE, or FILE_TEXTURE: most textures
are FUNC_TEXTURE. The only difference here is that FILE_TEXTURES receive a
slightly different TDsize value for blurring purposes.

TEXTURE_TYPE can be PARAMETRIC_MAP, SOLID_3D_MAP, or

ENVIRONMENT_MAP: most textures are PARAMETRIC_MAP.

SOLID_3D_MAP textures are textures that operate purely in 3D space and

require no information about the object’s (u,v) coordinates (setting this can
produce efficiencies because (u,v) coordinates do not need to be stored nor
computed).

ENVIRONMENT_MAP textures are textures that use the reflected ray to

calculate the color of the texture at any point. Textures that are environment
maps cannot be used for bump or displacement mapping.

TEXTURE_ABSOLUTE can be TRUE or FALSE. Textures that use parametric

mapping (the u, v coordinates) must set this to FALSE. Environment maps and solid
textures must set this flag to TRUE.

A Parametric Texture Prototype

int CALC ( AR_TextureData *texture )
{

24 Guide to Alias OpenModel

 The Application Program Interface (API) — CALC()

AR_TextureInfo*pInfo;
INFO_TYPE *pData;
float u, v;
AR_Rgba result;
pInfo = texture->TDdata;
pData = (INFO_TYPE *)( pInfo->user_texture_info );
u = texture->TDu;
v = texture->TDv;
/* Using the u,v values, calculate the texture color here. */
blurmult = texture->TDblurmult;
bluroffset = texture->TDbluroffset;
/* This assumes that the color has been placed in 'result'. */
/* texture->TDcolor MUST be set before returning. */
texture->TDcolor->r = result.r;
texture->TDcolor->g = result.g;
texture->TDcolor->b = result.b;
texture->TDcolor->a = result.a;
return( TRUE );
}
A Solid Texture Prototype
int CALC( AR_TextureData *texture )
{
INFO_TYPE *pData;
AR_TextureInfo*pInfo;
AR_Point *pt;
AR_Point pt2;
AR_Vector *norm;
AR_Rgba result;

pInfo = texture->TDdata;
pData = (INFO_TYPE *)( pInfo->user_texture_info );
pt = texture->TDhit;
norm = texture->TDnormal;
OCR_init_texture_transforms( pInfo, &pData->invdet);
/* Assuming pData->invdet exists. */

/* Define the texture space coordinates for the solid texture */

pt2.x = pt->x;
pt2.y = pt->y;
pt2.z = pt->z;
OCR_transform_point(&pt2, pInfo->invcurrTM);
/* Using the pt2.[x,y,z] and/or the normal (in 'norm'), calculate */
/* the texture color here. */

Guide to Alias OpenModel 25

The Application Program Interface (API) — CALC()

/* This assumes that the color has been placed in 'result'. */

/* texture->TDcolor MUST be set before returning. */
texture->TDcolor->r = result.r;
texture->TDcolor->g = result.g;
texture->TDcolor->b = result.b;
texture->TDcolor->a = result.a;
return (TRUE);
}
An Environment Texture Prototype
int CALC ( AR_TextureData *texture )
{
float length;
INFO_TYPE *pData;
AR_TextureInfo*pInfo;
AR_Point *pt;
AR_Vector norm;
AR_Rgba value;

pInfo = texture->TDdata;
pData = (INFO_TYPE *)( pInfo->user_texture_info );
OCR_init_texture_transforms( pInfo, NULL );
pt = texture->TDhit;

norm.x = texture->TDray->x;
norm.y = texture->TDray->y;
norm.z = texture->TDray->z;
/* Define the texture space coordinates for the solid texture */
pt2.x = pt->x;
pt2.y = pt->y;
pt2.z = pt->z;
OCR_transform_point(&pt2, pInfo->invcurrTM);
OCR_transform_vector(&norm, pInfo->invcurrTM);

/* Based on the normal and/or the point, calculate the value of the
environment */
/* function here. Place the calculated color in 'value'. In this
example, the */
/* Alpha channel is calculated by computing the luminance of the
color. */

texture->TDcolor->r = value.r;
texture->TDcolor->g = value.g;
texture->TDcolor->b = value.b;
texture->TDcolor->a

26 Guide to Alias OpenModel

 The Application Program Interface (API) — CALC()

= OCR_NTSC_LUMINANCE(value.r, value.g, value.b);

return( FALSE );
}

Guide to Alias OpenModel 27

Tutorial—Changing the OpenRender Template — Standard Alias Shader Data Items

Tutorial—Changing the OpenRender Template

In this section we detail which sections of the OpenRender Template file should be
modified to write your own OpenRender C code module.

The first step is to decide what type of data your module will need. To do this, you
need to know that Alias already has some standard data items that it maintains.
Each type of object (light/shader/texture) has a certain number of standard, Alias-
defined data items that are parsed, evaluated and initialized automatically. These
standard data items in the CALC routines in the data structures: AR_LightInfo,
AR_ShaderData or AR_TextureData (depending, of course, on which type of
OpenRender C module you are writing).

Note: It cannot be stressed enough that the values in the Alias supplied AR_
structures should not be changed by you at any time, unless explicitly
requested in the prototypes.

The following tables contain the fields in the various data structures for the CALC
routines. These types are defined in ALIAS OCR_types.h. Any fields not described
below are for Alias internal use only.

Standard Alias Shader Data Items

All values in the following AR_ShadeData structure are final values of the current
point. If any of these values have been textured, the values in these fields have had
the textures applied. The Normal and the crosspt have already been bump
mapped and displacement mapped if such textures were applied.

The only field in AR_ShadeData that can (and must) be modified by you is the
transcol field. This field must hold the result of the shading computation when the
shader returns.

28 Guide to Alias OpenModel

 Tutorial—Changing the OpenRender Template — AR_ShadeData Structure

AR_ShadeData Structure

Field Name Type Meaning

surfColor AR_Rgba * A pointer to the color of the surface at the
current point.
incandescence AR_Rgba The incandescence of the surface at the cur-
rent point.
surfTrans AR_Rgba The transparency of the surface at the cur-
rent point.
crosspt AR_Point * A pointer to the current point's coordinates
(x, y, z).
Normal AR_Vector The normal at the current point.
utangent AR_Vector The tangent in the U parametric direction.
vtangent AR_Vector The tangent in the V parametric direction.
Sight AR_Vector * A pointer to the normalized direction vector
of the incident ray.
lights AR_LightList * A list of lights that can possibly illuminate
this point.
transcol AR_Rgba * A pointer to the color behind the current
surface (see shader template).
refractive_inde double The refractive index of the surface.
x

void* user_shade_data place holder for per pixel user defined data

Standard Alias Light Data Items

AR_LightInfo Structure

Field Name Type Meaning

name char * The unique name of the light (not the
model name).
intensity float The intensity of the light.

Guide to Alias OpenModel 29

Tutorial—Changing the OpenRender Template — Standard Alias Texture Data Items

color AR_TextureType The color of the light.

transformed_color AR_Rgb The color of the light multiplied by the
intensity.
shadows AR_Boolean TRUE if shadows are to be calculated for
this light.
user_light_info void * This is a pointer to the data structure you
have defined.

AR_LightData Structure

ambient AR_Boolean TRUE if light contributes to ambient shading

diffuse AR_Boolean TRUE if light contributes to diffuse shading
specular AR_Boolean TRUE if light contributes to specular shading
intensity AR_Rgb Returned color of lighting
direction AR_Vector Returned direction from surface to light
void * user_data For user-defined data structures

computed_cosln AR_Boolean TRUE if cosln has been computed by the shader.

cosln float* The dot product between the surface normal and
the light vector.

Standard Alias Texture Data Items

Every texture must place results into the TDcolor field of the AR_TextureData
structure before returning successfully. Upon a successful texturing, the textures
must place values in each of the red, green, blue and alpha channels. If the
texturing is unsuccessful, then the value in the TDcolor field should not be
modified.

30 Guide to Alias OpenModel

 Tutorial—Changing the OpenRender Template — AR_TextureData Structure

AR_TextureData Structure

Field Name Type Meaning

TDdata AR_TextureInf Should only be used to get your INFO_TYPE data
o * structure.
TDu float The value of the U parametric coordinate at the
point of intersection.
TDv float The value of the V parametric coordinate at the
point of intersection.
TDsize float The projected length of the subtended pixel (used
for blurring in Alias textures).
TDhit AR_Point * A pointer to the world space coordinates of the cur-
rent point.
TDnormal AR_Vector * A pointer to the surface normal of the current point.
TDray AR_Vector * A pointer to the normalized direction vector of the
incident ray.
TDcolor AR_Rgba * A pointer to space for the result of the texture.
TDblurmult float The value for the blur multiplication.
TDbluroffset float The value for the blur offset.

Standard SDL Parameters

OpenRender C code modules let you extend the SDL syntax and increase the Alias
Renderer’s functionality. However, there are standard Alias SDL parameters that
you can use in your shaders, lights, and textures. This section outlines the SDL
parameters that Alias automatically parses, evaluates and calculates for your
OpenRender modules to use.

Note: The following lists are reserved SDL keywords. You cannot use these
keywords for your SDL extensions because the Alias field takes precedence.
For example, if you have a NODE field that you link to the SDL keyword
“color,” your field will never have anything put into it since the Alias shader
keyword “color” is already linked to an Alias defined NODE structure.

Guide to Alias OpenModel 31

Tutorial—Changing the OpenRender Template — Standard SDL Parameters

Standard SDL Shader Parameters

SDL keyword AR_ShaderInfo field

refractive_index AR_ShaderInfo->refractive_index
color AR_ShaderInfo->color
colour AR_ShaderInfo->color (note:same as above)
incandescence AR_ShaderInfo->incandescence
transparency AR_ShaderInfo->transparency
bump AR_ShaderInfo->rel_bump
displacement AR_ShaderInfo->rel_displacement
transparency_shade AR_ShaderInfo->transparency_shade
reflection_limit AR_ShaderInfo->reflection_limit
refraction_limit AR_ShaderInfo->refraction_limit
shadow_level_limit AR_ShaderInfo->shadow_level_limit
respect_reflection_map AR_ShaderInfo->respect_reflection_map
shading_map AR_ShaderInfo->shading_map
surface_width AR_ShaderInfo->surface_width
transparency_depth AR_ShaderInfo->transparency_depth
refraction_jitter AR_ShaderInfo->refraction_jitter
refraction_samples AR_ShaderInfo->refraction_samples
chromatic_abberation AR_ShaderInfo->chromatic_abberation
fill_color AR_ShaderInfo->hl_fill_color
line_thickness AR_ShaderInfo->hl_line_width
u_patch_lines AR_ShaderInfo->hl_isoparam_u
v_patch_lines AR_ShaderInfo->hl_isoparam_v
glow_intensity AR_ShaderInfo->glow_intensity
hide_glow_source AR_ShaderInfo->hide_glow_source

32 Guide to Alias OpenModel

 Tutorial—Changing the OpenRender Template — Standard SDL Parameters

Standard SDL Light Parameters

SDL keyword AR_LightInfo field

active AR_LightInfo->active
exclusive AR_LightInfo->exclusive
color AR_LightInfo->color
colour AR_LightInfo>color (note: same as above)
intensity AR_LightInfo->intensity
shadow AR_LightInfo->shadows
glow_type AR_LightInfo->glow->glow_type
halo_type AR_LightInfo->glow->halo_type
fog_type AR_LightInfo->glow->fog_type
glow_intensity AR_LightInfo->glow->glow_intensity
halo_intensity AR_LightInfo->glow->halo_intensity
fog_intensity AR_LightInfo->glow->fog_intensity
glow_spread AR_LightInfo->glow->glow_spread
halo_spread AR_LightInfo->glow->halo_spread
fog_spread AR_LightInfo->glow->fog_spread
glow_2D_noise AR_LightInfo->glow->glow_2Dnoise
fog_2D_noise AR_LightInfo->glow->fog_2Dnoise
glow_radial_noise AR_LightInfo->glow->glow_radial_noise
fog_radial_noise AR_LightInfo->glow->fog_radial_noise
glow_star_level AR_LightInfo->glow->glow_star_level
fog_star_level AR_LightInfo->glow->fog_star_level
glow_opacity AR_LightInfo->glow->glow_opacity
fog_opacity AR_LightInfo->glow->fog_opacity
radial_noise_frequency AR_LightInfo->glow->radial_frequency
star_points AR_LightInfo->glow->star_points
glow_rotation AR_LightInfo->glow->rotation

Guide to Alias OpenModel 33

Tutorial—Changing the OpenRender Template — Standard SDL Parameters

SDL keyword AR_LightInfo field

noise_uscale AR_LightInfo->glow->noise_uscale
noise_vscale AR_LightInfo->glow->noise_vscale
noise_uoffset AR_LightInfo->glow->noise_uoffset
noise_voffset AR_LightInfo->glow->noise_voffset
noise_threshold AR_LightInfo->glow->noise_threshold

34 Guide to Alias OpenModel

 Tutorial—Changing the OpenRender Template — Standard SDL Parameters

Standard SDL Texture Parameters

SDL keyword AR_TextureInfo field

ucoverage AR_TextureInfo->uscale
vcoverage AR_TextureInfo->vscale
urepeat AR_TextureInfo->urepeat
vrepeat AR_TextureInfo->vrepeat
utranslate AR_TextureInfo->utranslate
vtranslate AR_TextureInfo->vtranslate
rgbmult AR_TextureInfo->RGBAmult
amult AR_TextureInfo->RGBAmult
blurmult AR_TextureInfo->blurmult
uoffset AR_TextureInfo->uoffset
voffset AR_TextureInfo->voffset
rgboffset AR_TextureInfo->RGBAoffset
aoffset AR_TextureInfo->RGBAoffset
bluroffset AR_TextureInfo->bluroffset
rgbout AR_TextureInfo->RGBout
aout AR_TextureInfo->aout
uwrap AR_TextureInfo>uwrap
vwrap AR_TextureInfo->vwrap
worldspace AR_TextureInfo->worldspace
chordTexture AR_TextureInfo->chordTextured
rotate AR_TextureInfo->rotate
active AR_TextureInfo->active
mirror AR_TextureInfo->mirror
invert AR_TextureInfo->invert
color_remap AR_TextureInfo->color_remap
smear_map AR_TextureInfo->uv_offset

Guide to Alias OpenModel 35

Tutorial—Changing the OpenRender Template — Customizing the OpenRender Template File

SDL keyword AR_TextureInfo field

overlay AR_TextureInfo->overlay
transformation_name AR_TextureInfo->TM

Customizing the OpenRender Template File

This section walks through the changing of a very simple shader. The shader
calculates only the ambient and diffuse contribution from each light source. For this
example, we walk through the file simple_shader.c and extend it to calculate a
“glow” contribution as well.

Briefly examine the file simple_shader.c. It uses its own definition for “color.” This is
not necessary, since this field is also maintained by Alias in the AR_ShadeData
structure. The “color” field is defined here for clarity. Although you are free to use
the information passed into your shader(s) in the AR_ShadeData structure, it is
clearer if you define all the parameters you are going to use in your own data
structures (as you have done with “color” in the simple_shader.c example).

Copy the file simple_shader.c to a file called new_shader.c, and read new_shader.c
into your favorite editor.

The first thing to change is the data structures. Locate the NODE_TYPE and
INFO_TYPE data structures in the file and add “glow,” an AR_Rgb, to both data
structures. The structures should now look like:

typedef struct NODE_TYPE {

RR_ExpNode *diffuse_node;
RR_ExpNode *color_node;
RR_ExpNode *glow_node;
} NODE_TYPE;

typedef struct INFO_TYPE {

float diffuse;
AR_Rgb color;
AR_Rgb glow;
} INFO_TYPE;

Next, you must customize the name of this shader. Locate the MODULE_NAME
define—it should be only a few lines below the data structure definitions that you

36 Guide to Alias OpenModel

 Tutorial—Changing the OpenRender Template — Customizing the OpenRender Template File

just changed. Now change the MODULE_NAME to “new_shader” (or whatever you
choose to call it). This allows Alias-defined functions in OCR_predef_routines.h to
print out meaningful warning and error messages.

You want your new “glow” parameter to have a default. Let’s say that the default is a
nice red (200, 20, 10). Locate the line that reads:

static const int diffuse_default = 0.8;

and add the following line, to be the default for your new “glow” parameter:

static const AR_Rgb glow_default = (200.0, 20.0, 10.0);

The next thing you want to do is tell the Renderer which keyword to add to SDL,
and where to place information from that keyword in the data structures you have
just modified. Locate the PARAM_TAB[] array. This is the array that extends the
syntax of SDL. You want to have the “glow” parameter use “glow” as its keyword in
SDL, so you add the line beginning with “glow” to the following table:

static const OcrCtlParamTabType PARAM_TAB[]={

/*

*SDL
Node Field Info Field Info Type Default
param
*------- ---------- ---------- --------- ------ */
"ldiffuse", NODE(diff INFO(dif- SCALAR, (void*)&dif
use_node), fuse), fuse_default
,
"lcolor", NODE(colo INFO(color TRIPLE, (void*)&col
r_node), ), or_default,
"glow", NODE(glo INFO(glow) TRIPLE, (void*)&glo
w_node), , w_default,
NULL, 0, 0, 0, NULL
};

The new “glow” line must come before the line that starts with NULL. The line that
starts with NULL is used to terminate the list, and anything added after the NULL
line is ignored by the Alias Renderer. Once you have made the above change to
PARAM_TAB[], the Alias Renderer knows that when it sees the keyword “glow” in the
SDL file, the Renderer must place whatever “glow” is assigned into the NODE field

Guide to Alias OpenModel 37

Tutorial—Changing the OpenRender Template — Customizing the OpenRender Template File

“glow_node,” and that at evaluate time, the NODE field “glow_node” must be
evaluated into the INFO field “glow.” You have also told the renderer that “glow”
must be a TRIPLE (in this case, red, green, and blue) and that if there is no
keyword “glow” in the SDL file, the values you placed in “glow_default” are to be
used (see the next section, Notes on the PARAM_TAB Array, for more information).

Note: The SDL keyword for your “color” field is defined to be lcolor to avoid conflict
with the Alias defined keyword color. See the note at the top of Standard
SDL Parameters for more explanation.

The final change to make in order to add our new “glow” parameter to the simple
shader is to modify the CALC routine. Locate the line:

/* Calculate Transparency */
in the file. Just before this line, add the following code:

result.r += pUserInfo->glow.r;
result.g += pUserInfo->glow.g;
result.b += pUserInfo->glow.b;
Once you have done this, you have completed the modifications to your
“new_shader.” You can now write the file, exit your editor and compile
“new_shader.c.” Once you have compiled the shader, you can try it by adding the
following to an SDL file somewhere in the DEFINITION section:

create shader ( model = new_shader, filename = "new_shader.o" );

shader my_shader(
model = new_shader,
lcolor = (150, 150, 150), /* grey */
ldiffuse = 0.8,
glow = (20, 20, 180) /* blue */
);

Modify one of the surfaces in your SDL file so that it uses this new shader you have
just added, then render the SDL file.

Notes on the PARAM_TAB Array

The PARAM_TAB[] array is interpreted by the Parse and Evaluate routines. In the
following example array, the first row is an example of how an SDL parameter
keyword corresponds to a field in the NODE struct called fieldNODE and a field in
the INFO structure called fieldINFO.

38 Guide to Alias OpenModel

 Tutorial—Changing the OpenRender Template — Customizing the OpenRender Template File

typedef struct NODE_TYPE {

RR_ExpNode *fieldNODE;
RR_ExpNode *fieldColn;
} NODE_TYPE;

typedef struct INFO_TYPE{

intfieldINFO;
AR_RgbfieldColi;
}INFO_TYPE;

static const OcrCtlParamTabType PARAM_TAB[]={

/*
*SDL param Node Field Info Field Info Type Default
*------- ---------- ---------- --------- ------
*/
"paramSDL", NODE(fieldNODE), INFO(fieldINFO), SCALAR, NULL,
"mcolour", NODE(fieldColn), INFO(fieldColi), TRIPLE,
(void*)&ColDef,
"mcolor", NODE(fieldColn), INFO(fieldColi), DO_NOT_EVAL, NULL,
NULL, 0, 0, 0, NULL
};

Suppose you are adding a new sort of light to the SDL:

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

.
.
.
light (model=example, paramSDL=1.0);

The line starting with paramSDL in the above PARAM_TAB array associates the
NODE field fieldNODE with paramSDL for SDL parsing and with the INFO struct
field fieldINFO for evaluation. In this case, by the time the INIT() routine is called,
the field fieldINFO has the value 1.0 in it.

The next two lines of the above PARAM_TAB array assume that there is a color
field (fieldColn in the NODE struct and fieldColi in the INFO struct) that you
want to be associated with two synonymous SDL parameters (“mcolour” and
“mcolor”). Since you only want to evaluate the information in the NODE_TYPE
structure once, the second binding of an SDL keyword to a field must have the Info
Type set to DO_NOT_EVAL. All INFO fields that should not be evaluated, but can be
parsed, should have DO_NOT_EVAL in the type field.

Guide to Alias OpenModel 39

Tutorial—Changing the OpenRender Template — Customizing the OpenRender Template File

Data Types
There are several types of data that the Renderer can parse and evaluate. The
following table lists the types of data you can specify in the Info Type field of the
PARAM_TAB[] array.

Field Entry Description

SCALAR float, double, integer, boolean
TRIPLE color, point, vector
TEXTURE Checker, sWood, file, sFractal, etc.
FILENAME array of char (possibly with frame number extension)
TRANSFORM_REFERENCE (for use with solid textures)

There are usage examples of all of these Info Types in the example OpenRender
modules.

Changing Glow to a Texturable Parameter

In this section, you will change the glow parameter you just added to new_shader.c
into a texturable parameter. The first thing to do is edit new_shader.c. Locate the
INFO_TYPE data structure. Change the definition of glow from AR_Rgb to
AR_TextureType.

typedef struct INFO_TYPE{

float diffuse;
AR_Rgb color;
AR_TextureTypeglow;
}INFO_TYPE;

Note that its type remains RR_ExpNode in the NODE_TYPE structure.

Next, locate the definition of glow_default. All textures are 4-channel textures, so
the default for a texture must be an AR_Rgba. Therefore, you must change its
definition, and add a scalar to the default value:

static const AR_Rgba glow_default = (200.0, 20.0, 10.0, 0.0);

Next, locate the PARAM_TAB[] array. You must change the Info Type field from
TRIPLE to TEXTURE.

40 Guide to Alias OpenModel

 Tutorial—Changing the OpenRender Template — Customizing the OpenRender Template File

"glow", NODE(glow_node), INFO(glow), TEXTURE,

(void*)&glow_default,
Textures require initialization in the INIT() routine, so locate the OCR_Init()
routine. Currently it is an empty function. Add the following line to initialize the
texture:

static AR_Boolean
OCR_Init(
INFO_TYPE *pUserInfo
)
{
OCR_initialize_texture( pUserInfo->glow.map );
return TRUE;
}

Finally, the last change required is in the CALC routine. You must now call the CALC
routine for the texture before you add glow to the result. To do this, you need some
extra variables defined at the top of the CALC routine:

AR_TextureDatatx; /* Texture mapping variables */

AR_Rgba rgba;

Then, you need to set up the AR_TextureData structure so that the texture can
evaluate the value at the current location properly. Locate the code you put in to add
the glow to the result (it should look like:)

result.r += pUserInfo->glow.r;
result.g += pUserInfo->glow.g;
result.b += pUserInfo->glow.b;

Delete the above code (it will no longer work for textures) and replace it with:

/* Set up AR_TextureData structure. */

tx.TDgeom = pGeometry;
tx.TDray = &ray;
tx.TDnormal = &(pShadeData->Normal);
/* Set up location for result of texture. */
tx.TDcolor = &rgba;

/* Call the texture (this will work even if a literal or the */

/* default value was assigned to this parameter in SDL). */
OCR_INVOKE_MAPPING( tx, pInfo->reflectivity, pShadeData->Sight );

/* Add the textured glow to the result. */

Guide to Alias OpenModel 41

Tutorial—Changing the OpenRender Template — Modifying SDL files

result.r += rgba.r;
result.g += rgba.g;
result.b += rgba.b;
Notice how you added the values in rgba to the result after the texture had been
invoked. You could have taken the values out of tx.TDcolor as well, since it also
points to rgba.

If you write the file and compile it, you can now place a texture or a triple on the
glow parameter in the SDL file. Try running the Renderer on the same file you
modified last time (it has a constant, literal value for glow, and the image should
look no different from the last time you ran it). Now try placing a texture on the glow
parameter. Modify the SDL to read:

shader my_shader(
model = new_shader,
lcolor = (150, 150, 150), /* grey */
ldiffuse = 0.8,
glow = texture(
procedure = Checker,
urepeat = 20,
vrepeat = 20,
rgbout = (0, 150, 255),
contrast = 1.0,
color1 = (255, 255, 255),
color2 = (0, 0, 0)
)
);
Try rendering this modified SDL file. Notice how the object appears to be
checkered. Congratulations—you have just added a texturable attribute to your
OpenRender shader.

Modifying SDL files

The Alias Scene Description Language (SDL) has a new extension to allow you to
specify the OpenRender shaders, lights and textures. The new keyword is create.
The syntax for this keyword is as follows:

create [light|shader|texture] ( model = <model name>, filename =

"<filename.o>" );
After the create statement is placed in the SDL file, the OpenRender model you
have created can be used just like an Alias model. (Look at the simple_shader SDL
file in the OpenRender sdl directory for an example.)

42 Guide to Alias OpenModel

 Tutorial—Changing the OpenRender Template — Modifying SDL files

For example, if you have modified the OpenRender Template file to define a shader
that you want to call “glossy,” and you have compiled the modified OpenRender
Template file into a file called “glossy.o,” then the create command in SDL would
look like this:

create shader ( model = glossy, filename = glossy.o );

and subsequent uses of the shader would look like:

shader (model = glossy, ...... );

Of course, the remaining arguments to the shader “glossy” depend on what
parameters you have defined in the OpenRender Template file. You must create an
OpenRender code module in the SDL higher up in the file than where it is used (that
is, the OpenRender code module must be defined before it is used).

Guide to Alias OpenModel 43

Tutorial—The Scan Line Shader — The CALC Function

Tutorial—The Scan Line Shader

In V7.01, a new type of plug-in (the scan-line shader) was added to OpenRender.
Like all OpenRender shaders, the scan-line shader centers around a CALC function.
This CALC function gets called once per scan line. For example, if you are
rendering an image that is 640x480, your scan-line shader plug-in is called 480
times. Within the CALC function, your shader has access to the RGBA colors for all
pixels on the previous, current, and next scan lines, and also has access to any
custom data that you may need (more on this later).

Example code for this type of shader can be found in:

/usr/aw/alias/ODS/OpenRender/samples/plabel
or possibly:
/usr/aw/alias/ODS/OpenRender/samples/scanline

The CALC Function

Recall that the shader CALC function looks like:

static int CALC (

AR_ShaderInfo *pShader,
AR_GeometryInfo *ar_geom,
AR_ShadeData *pShadeData,
AR_OCR_ObjectInfo *object_info,
void *ni,
void *rt_ray_rec
)

For the scan-line shader, the scan-line data is found in the second parameter,
ar_geom. Typically you access the scan-line data by casting the ar_geom variable
to type AR_PoseShadeData:

AR_PostShadeData* postShadeData =
(AR_PostShadeData*) ar_geom;

where AR_PostShadeData is defined as:

typedef struct AR_PostShadeData {

AR_PostScanlineData* previous;
AR_PostScanlineData* current;
AR_PostScanlineData* next;

44 Guide to Alias OpenModel

 Tutorial—The Scan Line Shader —

AR_Rgba* previous_color;
AR_Rgba* current_color;
AR_Rgba* next_color;
int resolution;
char* image_output;
} AR_PostShadeData;

For each call to the CALC function, you have access to the current scan line, and
also the previous and next scan lines. If this is the first scan line, then the previous
scan-line pointer is NULL, and if this is the last scan line, the next scan line is NULL.
For example, to print out the RGB colors for all pixels in the current scan static int
nScanLine = 0;

for (int i=0;i<postShadeData->resolution;i++)

{
printf(“RGB of pixel (%4d,%4d) = (%4d,%4d,%4d)\n”,
i,nScanLine,current_color->[i].r,
current_color->[i].g,
current_color->[i].b);
}
nScanLine ++;

The size of the Image

The number of pixels per scan line can be found in the resolution field of the
AR_PostShadeData structure. The number of scan lines can be calculated by
counting the number of times the CALC function is called. If you need to know this
information up front, here is an easy way to do it:

static int nXSize;

static int nYSize;
// grab data on first call to CALC
if (postShadeData->previous == NULL)
{
nXSize = ar_render_options.xresolution;
nYSize = ar_render_options.yresolution;
}

Guide to Alias OpenModel 45

Tutorial—The Scan Line Shader — Passing other data

Passing other data

So far, we have seen that you can access the color information for each scan line,
but what if you want some other type of data. For instance, you may want to know
the normal vector, object id, object name, or some other piece of data. This is where
the previous, next, current fields of the AR_PostShadeData structure come into
play. For example, the current field is an array of pointers to data that is created in a
standard shader plug-in. If the pointer is NULL, then no data was created for that
pixel; if the pointer is not NULL, then another shader allocated a data structure for
this pixel.

This is best explained with an example. Please refer to the following directory and
files:

./ODS/OpenRender/ocr/samples/scanline

file: orNormal1.c - Source file for an OpenRender shader plug-in. This plug-in stores
the normal vector for each pixel in user data, which is later looked at in the scan-line
shader (orNormal2.c)

file: orNormal2.c - Source file for an OpenRender scan-line shader plug-in. This
plug-in gathers the normal vector data that was generated in orNormal1.c, and
stores the whole image worth of data into a new image.

file: orNormal.perl - This perl script reads the file input.sdl and generates the file
output.sdl. The input.sdl file is a normal sdl that you would save in Alias. The
output.sdl is a modified sdl that contains the load calls for the OpenRender plug-ins,
the image_shader stanza, and also adds a layered shader to all geometry. This
layered shader is orNormal1.c; this way, all geometry gets passed through this
shader.

file: runit - A script to run the perl script, render, and look at the results.

To run this example, please type ./runit

46 Guide to Alias OpenModel

 APPENDIX—Alias-defined API Functions — Passing other data

APPENDIX—Alias-defined API Functions

This section lists the functions (in ANSI C Prototype form) that Alias supplies for use
in your OpenRender C code modules. Each prototype listing is followed by a brief
description of the arguments and what the function does. All of these prototypes are
provided to you in the file OCR_api.h.

It should be pointed out that standard C library functions can be used in addition to
any of the functions listed below.

float OCR_random ()
This function returns a pseudo-random number between 0.0 and 1.0.

int OCR_reflect_ray (
AR_Vector *ray,
AR_Vector *normal,
AR_Vector *newray
)
This function takes three arguments, the incident ray, the surface normal (both
normalized), and space for the resultant reflected ray (newray). It returns a
normalized ray that points in the reflection direction.

void OCR_INVOKE_MAPPING (
AR_TextureData *pData,
AR_TextureInfo *pInfo,
AR_Point *ray
)
This function calls the texture referenced by the AR_TextureInfo pointer and returns
the result in pData->TDcolor, which must be initialized to point to an AR_Rgba
before the call. The argument ray is a pointer to the incident ray. This macro returns
the constant out value of the texture if no texture is present, or if the texture does
not apply to the current point. pData->TD[uv] is modified by this routine to equal
pData->TDgeom>[uv]center automatically.

int OCR_initialize_texture (
AR_TextureInfo *texture
)
This call initializes the texture referenced by the AR_TextureInfo pointer. This must
be called for each texturable field in your INFO structure. It should be called in the
INIT() routine only.

Guide to Alias OpenModel 47

APPENDIX—Alias-defined API Functions — Passing other data

int OCR_init_texture_transforms (
AR_TextureInfo *texture,
float *inverse_determanent
)
This function should be called at the top of the solid and environment texture's
CALC routine if you want to use save_transformation in the SDL to alter the
orientation of your solid texture. See the solid and environment texture prototypes
for an example of usage.

void
OCR_set_texture_type (
int status,
int type,
int absolute
)
This function is called from the OpenRender Template File's Eval_Local routine and
is used to tell the Alias Renderer what type of texture you have written. You should
not have to call this function. If you are writing a texture, you only need to modify the
three #defines that exist at the top of the example C files: TEXTURE_STATUS,
TEXTURE_TYPE, and TEXTURE_ABSOLUTE. See the Texture section for further
discussion of this function.

AR_Boolean
OCR_bind_forward_reference (
AR_Triple *original,
AR_Triple *thing_being_bound
)
This function is used in the COPY routine to allow a forward reference to be bound
across copies of an object. This function should be used only for positional
information where the value of the field is derived from a variable that is set to the
value of a current_position() statement elsewhere in SDL. See the Initialize
section of this document for more information on how to apply this function.

int
OCR_transform_point (
AR_Point* in_pt,
AR_Point* out_pt
)
This function applies the current transformation to in_pt and places the result in
out_pt. This function is mostly useful for transforming a light’s position into world
space, and should only be called in the INIT routine (random results otherwise). The
two arguments, in_pt and out_pt can point to the same AR_Point.

48 Guide to Alias OpenModel

 APPENDIX—Alias-defined API Functions — Passing other data

int
OCR_transform_normal (
AR_Point* in_norm,
AR_Point* out_norm
)
This function applies the current transformation to in_norm and places the result in
out_norm. This function is mostly useful for transforming a light’s direction based on
the transformation matrix, and should only be called in the INIT routine (random
results otherwise). The two arguments, in_norm and out_norm can point to the
same AR_Point.

Caution: out_norm is not normalized, and in_norm does not have to be normalized.

int
OCR_transform_tangent (
AR_Point* in_tan,
AR_Point* out_tan
)
This function applies the current transformation to in_norm and places the result in
out_norm. This function should only be called in the INIT routine (random results
otherwise). Tangents should not be normalized. The two arguments, in_tan and
out_tan can point to the same AR_Point.

int
OCR_texture_transform_point (
AR_Point* pt,
AR_Matrix matrix
)
This function applies the supplied matrix to the specified point (pt). It is used
mostly in solid and environment textures to transform the current intersection point
from world space back into object space (the space where the object was defined).
Applying this matrix to the point applies any save_transformation matrices that
were specified in the SDL.

int
OCR_texture_transform_vector (
AR_Vector* vector,
AR_Matrix matrix
)
This function applies the supplied matrix to the specified vector. In all other ways it
is similar to OCR_texture_transform_point().

void OCR_NORMALIZE(

Guide to Alias OpenModel 49

 APPENDIX—Alias-defined API Functions — Passing other data

double length,
AR_Vector vector
)
This C macro normalizes the specified vector, and places the length of the vector
(before normalization) in length.

int
OCR_matrix_initialize (
AR_Matrix matrix
)
This function sets the specified matrix to the identity matrix.

int
OCR_matrix_multiply (
float* matrix1,
float* matrix2,
float* result_matrix
)
This routine multiplies matrix1 by matrix2 and returns the resulting matrix in
result_matrix. The routine allows result_matrix to be one of matrix1 or
matrix2. This function can be called by casting your matrices to (float *).

int
OCR_matrix_invert (
AR_Matrix matrix_in,
AR_Matrix matrix_out
)
This routine inverts the matrix specified by matrix_in into matrix_out. The two
matrices cannot be the same matrix. If the matrix is not invertable,
OCR_fatal_error() is called and the renderer exits.

float OCR_noise3D (
double x,
double y,
double z
)
Given a location in three dimensions (x, y, z), this function returns a 3D,
continuous pseudo-random scalar value. See Ken Perlin's paper on Solid Textures
for more information.

float OCR_noise2D (
double x,
double y
)

Guide to Alias OpenModel 50

 APPENDIX—Alias-defined API Functions — Passing other data

Given a location in two dimensions (x, y), this function returns a 2D, continuous
pseudo-random scalar value. See Ken Perlin's paper on Solid Textures for more
information.

AR_Rgb OCR_color_noise2D (
double x,
double y
)
This function generates a continuous, non-repeating, 3D noise in two-dimensional
space.

float OCR_check_shadow (
AR_LightInfo *light,
double length,
AR_Vector *direction,
AR_Point *pt,
AR_Rgba *shadow_color
)
Useful in the Alias Raytracer only.

Given a pointer to the light to check for shadows on, this routine traces a ray from
the intersection point (pt) following the normalized direction vector that points
towards the light (direction). The shadow ray tracing stops after length units,
which should be passed in as the distance to the light source. The float value
returned is for backwards compatibility. The shadow_colour point contains the r,g,b
values to multiply into the final result to produce colored shadows in the raytracer.
This function can be called only from a Light CALC function in the raytracer.

int OCR_copy_TextureType (
AR_TextureType *pTo,
AR_TextureType *pFrom
)
This function copies the texture pFrom into pTo. pTo must not be NULL, but all fields
inside pTo are assumed to be NULL. If the structures cannot be copied for some
reason, an error message is printed and the renderer aborts.

char *OCR_allocate (
unsigned int size
)
This routine allocates size bytes of memory. Upon failure, it prints an “Out of
memory” message and aborts the renderer.

int

Guide to Alias OpenModel 51

 APPENDIX—Alias-defined API Functions — Passing other data

OCR_fatal_error (
char* error_string,
char* argument
)
This routine prints out an error message and then aborts the renderer. The
error_string may contain a printf()-like directive that prints out the argument in
the string.

For example:

OCR_fatal_error( "This integer is wrong: %d ", i );

If there is no printf()-like directive in the error_string, then the second

argument should be NULL.

For example:

OCR_fatal_error( "Problem initializing code.", NULL );

int OCR_message (
char* message_string,
char* argument
)
This routine is similar to OCR_fatal_error() except the renderer is not aborted.

void OCR_want_tangents()
This routine is for use in the Evaluate section of your shaders. It allows you to tell
the Alias renderer to create tangent information for objects that use that shader. By
default, if the object is not bump or displacement mapped, tangents are not created
for the object.

Guide to Alias OpenModel 52

 APPENDIX—Alias-defined API Functions — Passing other data

Guide to Alias OpenModel 53

 APPENDIX—Alias-defined API Functions — Passing other data

Guide to Alias OpenModel 54

 Index —

Index

Symbols
(void*)&color_default, 37
(void*)&diffuse_default, 37
(void*)&glow_default, 37

A
active 33, 35
Alias functions in OpenRender 18
ambient 30
amult 35
aoffset 35
aout 35
application program interface 18
AR_Boolean OCR_bind_forward_reference ( AR_Triple *original, AR_Triple
*thing_being_bound ) 48
AR_LightInfo 28
AR_LightInfo >color 33
AR_LightInfo->active 33
AR_LightInfo->exclusive 33
AR_LightInfo->glow->fog_2Dnoise 33
AR_LightInfo->glow->fog_intensity 33
AR_LightInfo->glow->fog_opacity 33
AR_LightInfo->glow->fog_radial_noise 33
AR_LightInfo->glow->fog_spread 33
AR_LightInfo->glow->fog_star_level 33
AR_LightInfo->glow->fog_type 33
AR_LightInfo->glow->glow_2Dnoise 33
AR_LightInfo->glow->glow_intensity 33
AR_LightInfo->glow->glow_opacity 33
AR_LightInfo->glow->glow_radial_noise 33
AR_LightInfo->glow->glow_spread 33
AR_LightInfo->glow->glow_star_level 33
AR_LightInfo->glow->glow_type 33
AR_LightInfo->glow->halo_intensity 33
AR_LightInfo->glow->halo_spread 33
AR_LightInfo->glow->halo_type 33
AR_LightInfo->glow->noise_threshold 34
AR_LightInfo->glow->noise_uoffset 34
AR_LightInfo->glow->noise_uscale 34

Guide to Alias OpenModel55

 Index —

AR_LightInfo->glow->noise_voffset 34
AR_LightInfo->glow->noise_vscale 34
AR_LightInfo->glow->radial_frequency 33
AR_LightInfo->glow->rotation 33
AR_LightInfo->glow->star_points 33
AR_LightInfo->intensity 33
AR_LightInfo->shadows 33
AR_Point 31
AR_PostShadeData 45
AR_Rgb OCR_color_noise2D ( double x, double y ) 51
AR_ShaderData 28
AR_ShaderInfo->chromatic_abberation 32
AR_ShaderInfo->color 32
AR_ShaderInfo->glow_intensity 32
AR_ShaderInfo->hide_glow_source 32
AR_ShaderInfo->hl_fill_color 32
AR_ShaderInfo->hl_isoparam_u 32
AR_ShaderInfo->hl_isoparam_v 32
AR_ShaderInfo->hl_line_width 32
AR_ShaderInfo->incandescence 32
AR_ShaderInfo->reflection_limit 32
AR_ShaderInfo->refraction_jitter 32
AR_ShaderInfo->refraction_limit 32
AR_ShaderInfo->refraction_samples 32
AR_ShaderInfo->refractive_index 32
AR_ShaderInfo->rel_bump 32
AR_ShaderInfo->rel_displacement 32
AR_ShaderInfo->respect_reflection_map 32
AR_ShaderInfo->shading_map 32
AR_ShaderInfo->shadow_level_limit 32
AR_ShaderInfo->surface_width 32
AR_ShaderInfo->transparency 32
AR_ShaderInfo->transparency_depth 32
AR_ShaderInfo->transparency_shade 32
AR_TextureData 28
AR_TextureInfo 31
AR_TextureInfo >uwrap 35
AR_TextureInfo->active 35
AR_TextureInfo->aout 35
AR_TextureInfo->blurmult 35
AR_TextureInfo->bluroffset 35
AR_TextureInfo->chordTextured 35
AR_TextureInfo->color_remap 35
AR_TextureInfo->invert 35
AR_TextureInfo->mirror 35

Guide to Alias OpenModel56

 Index —

AR_TextureInfo->overlay 36
AR_TextureInfo->RGBAmult 35
AR_TextureInfo->RGBAoffset 35
AR_TextureInfo->RGBout 35
AR_TextureInfo->rotate 35
AR_TextureInfo->TM 36
AR_TextureInfo->uoffset 35
AR_TextureInfo->urepeat 35
AR_TextureInfo->uscale 35
AR_TextureInfo->utranslate 35
AR_TextureInfo->uv_offset 35
AR_TextureInfo->voffset 35
AR_TextureInfo->vrepeat 35
AR_TextureInfo->vscale 35
AR_TextureInfo->vtranslate 35
AR_TextureInfo->vwrap 35
AR_TextureInfo->worldspace 35
AR_Vector 31

B
blur multiplication 31
blur offset 31
blurmult 35
bluroffset 35
bump 32

C
CALC 19
CALC Function in scanline shader 44
CALC routines 28
calculate 16
char *OCR_allocate ( unsigned int size ) 51
chordTexture 35
chromatic_abberation 32
color 30, 32, 33
color_remap 35
colour 32, 33
computed_cosln 30
configure a user account 2
cosln 30
crosspt 29
current fields 46
customizing OpenRender template 36

Guide to Alias OpenModel57

 Index —

D
data types 40
diffuse 30
direction 30
displacement 32

E
environment texture prototype 26
evaluate 10
exclusive 33

F
FILENAME 40
fill_color 32
float OCR_check_shadow ( AR_LightInfo *light, double length, AR_Vector *direction,
AR_Point *pt, AR_Rgba *shadow_color ) 51
float OCR_noise2D ( double x, double y ) 50
float OCR_noise3D ( double x, double y, double z ) 50
float OCR_random 47
fog_2D_noise 33
fog_intensity 33
fog_opacity 33
fog_radial_noise 33
fog_spread 33
fog_star_level 33
fog_type 33
FREE 18
free 17

G
glow 37, 40
glow_2D_noise 33
glow_intensity 32, 33
glow_opacity 33
glow_radial_noise 33
glow_rotation 33
glow_spread 33
glow_star_level 33
glow_type 33

H
halo_intensity 33
halo_spread 33
halo_type 33
hide_glow_source 32

Guide to Alias OpenModel58

 Index —

I
incandescence 29, 32
INFO(color), 37
INFO(diffuse) 37
INFO(glow), 37
INIT 18
initialize 11
Installation 2
Installation Procedure 2
int OCR_copy_TextureType ( AR_TextureType *pTo, AR_TextureType *pFrom ) 51
int OCR_fatal_error ( char* error_string, char* argument ) 51
int OCR_init_texture_transforms ( AR_TextureInfo *texture, float *inverse_determanent ) 48
int OCR_initialize_texture ( AR_TextureInfo *texture ) 47
int OCR_matrix_initialize ( AR_Matrix matrix ) 50
int OCR_matrix_invert ( AR_Matrix matrix_in, AR_Matrix matrix_out ) 50
int OCR_matrix_multiply ( float* matrix1, float* matrix2, float* result_matrix ) 50
int OCR_message ( char* message_string, char* argument ) 52
int OCR_reflect_ray ( AR_Vector *ray, AR_Vector *normal, AR_Vector *newray ) 47
int OCR_texture_transform_point ( AR_Point* pt, AR_Matrix matrix ) 49
int OCR_texture_transform_vector ( AR_Vector* vector, AR_Matrix matrix ) 49
int OCR_transform_normal ( AR_Point* in_norm, AR_Point* out_norm ) 49
int OCR_transform_point ( AR_Point* in_pt, AR_Point* out_pt ) 48
int OCR_transform_tangent ( AR_Point* in_tan, AR_Point* out_tan ) 49
intensity 29, 30, 33
interface, application program 18
Introduction 7
invert 35
IRIX 5 2
IRIX 6.2 2
IRIX version 2
for OpenRender 2

L
lcolor 37
ldiffuse 37
length of subtended pixel 31
light data items, standard 29
light prototype 22
lights 29
line_thickness 32

M
mirror 35
modifying light data items 28
modifying OpenRender template 28

Guide to Alias OpenModel59

 Index —

modifying SDL files 42

modifying shader data items 28
modifying texture data items 28

N
name 29
next fields 46
NODE(color_node), 37
NODE(diffuse_node) 37
NODE(glow_node), 37
noise_threshold 34
noise_uoffset 34
noise_uscale 34
noise_voffset 34
noise_vscale 34
Normal 29
normalized direction vector 31
NULL, 37

O
OpenRender template 28
OpenRender V7.5 2
overlay 36

P
PARAM_TAB array 38
parameters, SDL 31
parametric texture prototype 24
parse 10
passing data 46
passing normal vector data 46
passing object id data 46
passing object name data 46
pixels per scanline 45
previous fields 46
prototype, environment texture 26
prototype, light 22
prototype, parametric texture 24
prototype, shader 20
prototype, solid texture 25

R
radial_noise_frequency 33
reflection_limit 32
refraction_jitter 32

Guide to Alias OpenModel60

 Index —

refraction_limit 32
refraction_samples 32
refractive_index 29, 32
rendering overview 9
resolution field 45
respect_reflection_map 32
rgbmult 35
rgboffset 35
rgbout 35
rotate 35

S
sample code 4
SCALAR 40
ScanLine Shader 44
ScanLine Shader plugin 44
SDL keywords 31
SDL path variable 5
shader data items, standard 28
shader prototype 20
shading_map 32
shadow 33
shadow catchers 6
shadow_level_limit 32
shadows 30
Sight 29
smear_map 35
solid texture prototype 25
specular 30
standard SDL parameters 31
star_points 33
surface normal 31
surface_width 32
surfColor 29
surfTrans 29

T
TDblurmult 31
TDbluroffset 31
TDcolor 31
TDdata 31
TDhit 31
TDnormal 31
TDray 31
TDsize 31

Guide to Alias OpenModel61

 Index —

TDu 31
TDv 31
test OpenRender installation 2
testing OpenRender 3
TEXTURE 40
texture 23
texture prototype 24
texture result 31
transcol 28, 29
TRANSFORM_REFERENCE 40
transformation_name 36
transformed_color 30
transparency 32
transparency_depth 32
transparency_shade 32
TRIPLE 40
tutorial 28
tutorial - scanline shader 44

U
U parametric coordinate 31
u_patch_lines 32
ucoverage 35
uoffset 35
urepeat 35
user_light_info 30
user_shade_data 29
user-defined functions 18
utangent 29
utranslate 35
uwrap 35

V
V parametric coordinate 31
v_patch_lines 32
V5.1.1 Changes 7
vcoverage 35
version of IRIX, determining 2
voffset 35
void * 30
void OCR_INVOKE_MAPPING ( AR_TextureData *pData, AR_TextureInfo *pInfo,
AR_Point *ray ) 47
void OCR_NORMALIZE( double length, AR_Vector vector ) 49
void OCR_set_texture_type ( int status, int type, int absolute ) 48
void OCR_want_tangents() 52

Guide to Alias OpenModel62

 Index —

void* 29
vrepeat 35
vtangent 29
vtranslate 35
vwrap 35

W
world space coordinates 31
worldspace 35

Guide to Alias OpenModel63