RRPIXL ( nopts, iopts, optdta, entys, transf, vmatrx, pixdef, litdef, ifail )
=============================================================================
Generate shaded picture (pixel) data.
Receives:
<KI_int_nitems> *nopts --- number of options in 'iopts'
KI_cod_rrop iopts[nopts] --- rendering options
<KI_tag_list_dbl> optdta[nopts] --- option data lists
KI_tag_list_entity *entys --- entities to render
<KI_tag_list_<transform>> *transf --- entity transforms
KI_dbl_view_mx vmatrx[16] --- viewing transform matrix
KI_tag_list_dbl *pixdef --- image to pixel map
KI_tag_list_list *litdef --- light source definitions
Returns:
KI_cod_error *ifail --- failure indicator
Specific errors:
KI_abort_from_go Rendering aborted by GO
KI_general_body General body supplied in list
KI_bad_light_source Invalid light source definition
KI_bad_pixel_map Invalid pixel map definition
KI_bad_view_mx Invalid view matrix
KI_wrong_transf Unsuitable transform
KI_not_same_length Entity and transform lists are of different lengths
KI_wrong_entity_in_list Entity is not a part
KI_bad_option_data Option data incorrect for specified options
Description:
RRPIXL outputs, through the Graphical Output interface (GO), pixel data
constituting a shaded picture of the entities.
RRPIXL can only render assemblies and complete bodies; it cannot render
individual faces or edges. General bodies are not supported.
Transforms may only contain translation and rotation components. Reflections,
scales and shears are not allowed.
The data output is selected by options in 'iopts'. For some options the output
is further controlled by data in a real list whose tag is passed in the
corresponding entry in 'optdta'. If no data is required for an option a null
tag should be passed.
Options accepted are:-
Option Contents of option data
===================================================================
RROPTR: TRansform none
RROPPS: PerSpective none
RROPAN: ANti-alias none
RROPSF: Surface-reFlec (1) Coefficient of specular reflection [0-1]
(2) Proportion of colour in highlights [0-1]
(3) Coefficient of diffuse reflection [0-1]
(4) Coefficient of ambient reflection [0-1]
(5) Reflection power [>=1]
RROPDM: Depth-Modulation (1) Depth modulation factor [0-1]
RROPFC: Face-Colour (1,2,3) Intensity of red, green, blue [0-1]
RROPBK: BacKground-colour(1,2,3) Intensity of red, green, blue [0-1]
RROPTL: TransLucence none
Option RROPTR is required if any of the entities is to be rendered in a
transformed position (e.g. as part of an assembly). If it is not specified,
the contents of 'transf' are ignored, and entities are rendered in their
local coordinate system.
Option RROPPS should be specified if a perspective view is required; by
default the system will produce a view from infinity, taking only the
view direction from 'vmatrx'.
Option RROPAN causes the pixel data to be anti-aliased, reducing the
'staircase' effect at face boundaries.
Each face to be rendered may have a reflectivity (TYSARF) attribute attached,
indicating its reflectivities of various sorts (specular, diffuse etc.).
Normally, any faces lacking a reflectivity attribute will be rendered with a
set of system default values. Option RROPSF can be used to specify values
which override the default values.
Option RROPDM can be used to specify depth modulation, whereby pixel
intensity is reduced on surfaces far from the eye. The value must be in the
range 0 (no depth modulation) to 1 (maximum depth modulation); the default
is 0.3.
Each face to be rendered may have a colour (TYSACO) attribute attached,
indicating its colour. Normally, any faces without a colour attribute will be
rendered with a system default colour. Option RROPFC can be used to override
the default.
To perform anti-aliasing correctly the system must know the background
colour. The system default background colour is black. If anti-aliasing is
selected, option RROPBK can be used to specify a background colour which
overrides the default.
Option RROPTL causes any faces with a translucence (TYSATR) attribute
attached to be rendered as translucent according to the values in the
attribute. If this option is not given translucence atributes are ignored.
'pixdef' is a list of six reals which defines the mapping of points from the
image space defined by 'vmatrx' to pixels in a pixel space thus:
Model --- vmatrx ---> Image --- pixdef ---> Pixel
Space Space Space
The six values are interpreted as follows:
(1) npixel_x Number of columns in pixel array
(2) npixel_y Number of rows in pixel array
(3) pixel_size_x Width of a pixel in image space units
(4) pixel_size_y Height of a pixel in image space units
(5) image_origin_x } Position of image-space origin in
(6) image_origin_y } pixel space
The pixel array has dimensions [npixel_x,npixel_y]. Element [1,1] of the
pixel array is at the top left of the picture:-
+------------------->x
| 1,1 2,1 3,1 ...
| 1,2 2,2 3,2 ...
| ... x,y
V
y
The pixel size defines the scaling from image space into the pixel array.
Image_origin_x and image_origin_y define the translation between image space
and pixel space. Note that if (image_origin_x,image_origin_y) are given as
(1,1) the image origin would be rendered at the bottom right-hand corner of
pixel (1,1); or if given as (0.5,0.5) the image origin would be rendered at
the centre of pixel (1,1). In normal use these values should be given as
(npixel_x/2,npixel_y/2) which maps the image origin to the centre of the pixel
array.
The equations for converting an image space point (image_x,image_y) into
pixel array indices (pixel_x,pixel_y) are:-
pixel_x = INT( image_origin_x + image_x/pixel_size_x )
pixel_y = INT( image_origin_y - image_y/pixel_size_y )
If pixel_x is not in the range [1 - npixel_x] or pixel_y is not in the range
[1 - npixel_y] the image point is not rendered.
'litdef' is a list of light sources, each defined by a list of reals as
follows:
(1) Type of source:-
1 => point source at infinity
3 => ambient light (only one ambient light is allowed)
(2,3,4) Intensity of red, green, blue in source [0-1]
(5,6,7) Model space direction to point source (not required for
ambient light).
Mathematics of the lighting model
---------------------------------
The computation of pixel intensity depends on the choices made for the
coefficients used in the equations modelling the illumination of a point
on a surface in line with the pixel and the eye.
Additionally (R,G,B) vectors specify the intensity and colours of the
ambient lighting, point lights, surface colour and background colour.
Let RA be the coefficient of ambient reflectivity
RD be the coefficient of diffuse reflectivity
RS be the coefficient of specular reflectivity
RH be the proportion of face colour in the specular highlights
RP be the coefficient of specular power
RT be the coefficent of transparency
DM be the coefficient of depth modulation
and Z be the distance of the point from the eye
Z0 be the minimum distance from the eye over the whole image
Z1 be the maximum distance from the eye over the whole image
and the (R,G,B) vectors
LAi be the intensity of the ambient light
LSi be the intensity of the point source light
FCi be the face colour intensities
BKi be the background colour intensities (all for i=R,G,B)
and the direction vectors
N be the normal of the surface at the point
L be the direction towards the point source light
H be the direction from the point source light to the eye
Then INTENSITY = DEPTH_INTENSITY + TRANSMITTED_INTENSITY
where DEPTH_INTENSITY = (1 - DM * (Z - Z0 )/(Z1 - Z0)) * TRANSMITTED_INTENSITY
TRANSMITTED_INTENSITY = RT * BACKGROUND_INTENSITY
BACKGROUND_INTENSITY = BK if there is no surface behind this one
else the depth intensity due to that surface
SURFACE_INTENSITY = IA + ID + IS
and IA is the intensity of illumination from the ambient light
ID is the intensity of diffuse illumination from all point sources
IS is the intensity of specular illumination from all point sources
IAi = RA * LAi * FCi
IDi = RD * LSi * FCi * (N.L) if N.L > 0 else 0
ISi = RS * LSi * (1 - RH + RH * Fi ) * ((N.H)** RP)
if N.H > 0 else 0
with the terms IS and ID summed for each point source present.
