# The "vrender" Package

These routines are meant to provide support for volume rendering. Most of the hard work in setting up the geometry, projections and making use of multiple CPUs is done in the package. The application "just" needs to provide the user interface, display canvas and shading algorithms. NOTE: THIS PACKAGE IS WORK IN PROGRESS. THE INTERFACE MAY CHANGE IN THE NEXT RELEASE, POSSIBLY WITHOUT NOTICE.

Library: karma
Link With: -lkarma

#### Functions

vrender_create_context | Create a context for volume rendering.
vrender_set_context_attributes | Set the attributes for a volume rendering context.
vrender_get_context_attributes | Get the attributes for a volume rendering context.
vrender_register_shader | Register a shader function.
vrender_change_shader_blank_packet | Change blank value for a particular shader.
vrender_get_shaders | Get the names of all registered shaders.
vrender_to_buffer | Render a scene in a volume rendering context to a buffer.
vrender_collect_ray | Collect a ray projected from an image plane into a volume.
vrender_project_3d | Project a point in 3-dimensional space onto a view plane.
vrender_compute_caches | Compute cache for volume rendering context.
vrender_image_desc_notify_func | Register image descriptor change callback.
vrender_cache_notify_func | Register cache computed callback.
vrender_view_notify_func | Register view changed computed callback.
vrender_message_notify_func | Register message callback.
vrender_client_notify_func | Register new client callback.
vrender_get_eye_info | Get eye information.
vrender_show_stats | Show distributed rendering statistics.
vrender_send_message | Send a message to all "VRENDER_private" clients.

#### Prototype Functions

vrender_PROTO_render_notify_func | Volume rendering completed callback.
vrender_PROTO_image_desc_notify_func | Image descriptor changed callback.
vrender_PROTO_cache_notify_func | Cache computed callback.
vrender_PROTO_view_notify_func | View changed callback.
vrender_PROTO_message_notify_func | Message received callback.
vrender_PROTO_client_notify_func | Client connected callback.

#### Tables

vrender_ATTRIBUTES | List of attributes volume rendering contexts
vrender_EYES | List of eye views
vrender_EYE_MASKS | List of eye view masks

## Functions

KVolumeRenderContext vrender_create_context (void *info, ...)

Create a context for volume rendering.

Parameters:

- info : An arbitrary information pointer associated with the context.
- ... : The optional list of parameter attribute-key attribute-value pairs must follow. This list must be terminated with the value VRENDER_CONTEXT_ATT_END. See vrender_ATTRIBUTES for a list of defined attributes.

Returns: A KVolumeRenderContext on success, else NULL.
Multithreading Level: Unsafe

flag vrender_set_context_attributes (KVolumeRenderContext context, ...)

Set the attributes for a volume rendering context.

Parameters:

- context : The volume rendering context.
- ... : The optional list of parameter attribute-key attribute-value pairs must follow. This list must be terminated with the value VRENDER_CONTEXT_ATT_END. See vrender_ATTRIBUTES for a list of defined attributes.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag vrender_get_context_attributes (KVolumeRenderContext context, ...)

Get the attributes for a volume rendering context.

Parameters:

- context : The volume rendering context.
- ... : The optional list of parameter attribute-key attribute-value-ptr pairs must follow. This list must be terminated with the value VRENDER_CONTEXT_ATT_END. See vrender_ATTRIBUTES for a list of defined attributes.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

void vrender_register_shader (void (*slow_func) (), void (*fast_func) (), CONST char *name, packet_desc *pack_desc, CONST char *blank_packet, void *info, flag front)

Register a shader function.

Parameters:

- slow_func : The slow shader function.
- fast_func : The fast shader function. If this is NULL the slow function will always be used.
- name : The name of the shader function.
- pack_desc : The packet descriptor describing the output image pixels. A copy is made, hence the original may be deallocated.
- blank_packet : A pointer to a sample packet containing blank data.
- info : An arbitrary information pointer associated with the shader.
- front : If TRUE, the new shader is placed at the front of the list, else it is placed at the back of the list.

Returns: Nothing. The process aborts on error.
Multithreading Level: Unsafe

void vrender_change_shader_blank_packet (CONST char *name, CONST char *blank_packet)

This routine will change the data used to write blank values for a particular shader.

Parameters:

- name : The name of the shader.
- blank_packet : A pointer to a sample packet containing blank data.

Returns: Nothing.
Multithreading Level: Unsafe

CONST char ** vrender_get_shaders (unsigned int *num_shaders)

Get the names of all registered shaders.

Parameters:

- num_shaders : The number of registered shaders is written here.

Returns: An array of shader names on success, else NULL. This array must be deallocated when no longer needed. The individual names must NOT be deallocated.
Multithreading Level: Unsafe

flag vrender_to_buffer (KVolumeRenderContext context, char *left_buffer, char *right_buffer, double *min, double *max, void (*notify_func) (void *info), void *info)

Render a scene in a volume rendering context to a buffer.

Parameters:

- context : The volume rendering context.
- left_buffer : The left eye buffer to render into. This must be correctly allocated.
- right_buffer : The right eye buffer to render into. If this is NULL no right eye view is rendered and a monoscopic image is rendered into the left eye buffer.
- min : The minimum value in the rendered images(s) is written here.
- max : The maximum value in the rendered images(s) is written here.
- notify_func : The function that is called when the rendering is completed. The prototype function is vrender_PROTO_render_notify_func.
- info : The arbitrary information pointer.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe per context.
Note:

- This function may block.

CONST signed char * vrender_collect_ray (KVolumeRenderContext context, unsigned int eye_view, Kcoord_2d pos_2d, Kcoord_3d *ray_start, Kcoord_3d *direction, float *t_enter, float *t_leave, unsigned int *ray_length)

Collect a ray projected from an image plane into a volume.

Parameters:

- context : The volume rendering context. This specifies the volume and view information.
- eye_view : The eye which sees the ray. See vrender_EYES for a list of legal values.
- pos_2d : The 2-dimensional position in the image plane to project from.
- ray_start : The 3-dimensional position of the starting point of the ray is written here. This point lies on the raster plane.
- direction : The 3-dimensional direction vector of the ray is written here. This is not normalised.
- t_enter : The distance down the ray corresponding to the first voxel is written here.
- t_leave : The distance down the ray corresponding to the last voxel is written here.
- ray_length : The length of the ray through the volume is written here. If the ray does not intersect the volume, 0 is written here.

Returns: A pointer to the collected ray. This is a statically allocated array per context which is updated on each call. On error NULL is returned.
Multithreading Level: Unsafe per context.

flag vrender_project_3d (KVolumeRenderContext context, unsigned int eye_view, Kcoord_3d point_3d, Kcoord_2d *point_2d, flag test_visible)

Project a point in 3-dimensional space onto a view plane.

Parameters:

- context : The volume render context which determines the view information.
- eye_view : The eye which will see the point. See vrender_EYES for a list of legal values.
- point_3d : The 3 dimensional point to be projected.
- point_2d : The projected 2 dimensional point will be written here.
- test_visible : If TRUE, the point is tested for visibility.

Returns: TRUE if the point is visible, else FALSE if it would be obscured by the volume or test_visible is FALSE.
Multithreading Level: Unsafe

void vrender_compute_caches (KVolumeRenderContext context, unsigned int eyes, flag notify)

This routine will compute the caches for the specified eyes. This speeds up subsequent rendering several times. Nothing is done if the cache(s) are already computed.

Parameters:

- context : The volume render context.
- eyes : A bitmask specifying which eye views to compute. The bitmask may be constructed by ORing some values. See vrender_EYE_MASKS for a list of masks.
- notify : If TRUE any functions registered with vrender_cache_notify_func will be called.

Returns: Nothing.
Multithreading Level: Unsafe

KCallbackFunc vrender_image_desc_notify_func (KVolumeRenderContext context, void (*func) (KVolumeRenderContext context, void **info), void *info)

This routine will register a function which should be called whenever the output image descriptor is changed.

Parameters:

- context : The volume render context.
- func : The routine to be called. The prototype function is vrender_PROTO_image_desc_notify_func
- info : The initial arbitrary information pointer.

Returns: A KCallbackFunc object on success. On failure, the process aborts
Multithreading Level: Unsafe

KCallbackFunc vrender_cache_notify_func (KVolumeRenderContext context, void (*func) (KVolumeRenderContext context, void **info, uaddr eyes), void *info)

This routine will register a function which should be called whenever the cache for one or more eye views is computed.

Parameters:

- context : The volume render context.
- func : The routine to be called. The prototype function is vrender_PROTO_cache_notify_func
- info : The initial arbitrary information pointer.

Returns: A KCallbackFunc object on success. On failure, the process aborts
Multithreading Level: Unsafe

KCallbackFunc vrender_view_notify_func (KVolumeRenderContext context, void (*func) (KVolumeRenderContext context, void **info), void *info)

This routine will register a function which should be called whenever the view for a context is changed.

Parameters:

- context : The volume render context.
- func : The routine to be called. The prototype function is vrender_PROTO_view_notify_func. This is called after view information has been computed, but before any cache information is computed.
- info : The initial arbitrary information pointer.

Returns: A KCallbackFunc object on success. On failure, the process aborts
Multithreading Level: Unsafe

KCallbackFunc vrender_message_notify_func (KVolumeRenderContext context, void (*func) (KVolumeRenderContext context, void **info, KVolumeRenderMessage *msg), void *info)

This routine will register a function which should be called whenever a message is received from the master.

Parameters:

- context : The volume render context.
- func : The routine to be called. The prototype function is vrender_PROTO_message_notify_func. This is called when a message has been received.
- info : The initial arbitrary information pointer.

Returns: A KCallbackFunc object on success. On failure, the process aborts
Multithreading Level: Unsafe

KCallbackFunc vrender_client_notify_func (KVolumeRenderContext context, void (*func) (KVolumeRenderContext context, void **info), void *info)

This routine will register a function which should be called whenever a new client connects to the master.

Parameters:

- context : The volume render context.
- func : The routine to be called. The prototype function is vrender_PROTO_client_notify_func. This is called when a client has connected.
- info : The initial arbitrary information pointer.

Returns: A KCallbackFunc object on success. On failure, the process aborts
Multithreading Level: Unsafe

void vrender_get_eye_info (KVolumeRenderContext context, unsigned int eye_view, Kcoord_3d *ras_centre, Kcoord_3d *direction, Kcoord_3d *horizontal)

Get eye information.

Parameters:

- context : The volume render context which determines the view information.
- eye_view : The eye which will see the point. See vrender_EYES for a list of legal values.
- ras_centre : The centre of the raster plane is written here.
- direction : The direction towards infinity is written here.
- horizontal : The horizontal direction vector is written here.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void vrender_show_stats (KVolumeRenderContext context, FILE *fp)

Show distributed rendering statistics.

Parameters:

- context : The volume render context.
- fp : The file to write the statistics to. If this is NULL, stdout is used.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void vrender_send_message (KVolumeRenderContext context, unsigned long command, CONST char *message, unsigned int length, flag sync)

Send a message to all "VRENDER_private" clients.

Parameters:

- context : The volume render context.
- command : The 32 bit command.
- message : The message data.
- length : The length of the message in bytes.
- sync : If TRUE the function will not return until all clients have received and acknowledged the message.

Returns: Nothing.
Multithreading Level: Unsafe

## Prototype Functions

void vrender_PROTO_render_notify_func (void *info)

This routine registers the completion of a volume render request.

Parameters:

- info : The arbitrary information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

void vrender_PROTO_image_desc_notify_func (KVolumeRenderContext context, void **info)

This routine is called when the output image descriptor is changed.

Parameters:

- context : The volume render context.
- info : A pointer to the arbitrary information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

void vrender_PROTO_cache_notify_func (KVolumeRenderContext context, void **info, uaddr eyes)

This routine is called when the cache for one or more eye views is computed.

Parameters:

- context : The volume render context.
- info : A pointer to the arbitrary information pointer.
- eyes : A bitmask specifying which eye views to compute. The bitmask may be constructed by ORing some values. See vrender_EYE_MASKS for a list of masks.

Returns: Nothing.
Multithreading Level: Unsafe

void vrender_PROTO_view_notify_func (KVolumeRenderContext context, void **info)

This routine is called when the view is changed.

Parameters:

- context : The volume render context.
- info : A pointer to the arbitrary information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

void vrender_PROTO_message_notify_func (KVolumeRenderContext context, void **info, KVolumeRenderMessage *msg)

This routine is called when a message is received from the master

Parameters:

- context : The volume render context.
- info : A pointer to the arbitrary information pointer.
- msg : The message.

Returns: Nothing.
Multithreading Level: Unsafe

void vrender_PROTO_client_notify_func (KVolumeRenderContext context, void **info)

This routine is called when a new client connects to the master.

Parameters:

- context : The volume render context.
- info : A pointer to the arbitrary information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

## Tables

vrender_ATTRIBUTES List of attributes volume rendering contexts

Name | Get Type | Set Type | Meaning
VRENDER_CONTEXT_ATT_END |  |  | End of varargs list
VRENDER_CONTEXT_ATT_CUBE | iarray * | iarray | Volume
VRENDER_CONTEXT_ATT_VIEW | view_specification * | view_specification * | Current view
VRENDER_CONTEXT_ATT_SHADER |  | CONST char * | Shader name
VRENDER_CONTEXT_ATT_SUBCUBE_X_START | unsigned long * | unsigned long | X start
VRENDER_CONTEXT_ATT_SUBCUBE_X_END | unsigned long * | unsigned long | X end
VRENDER_CONTEXT_ATT_SUBCUBE_Y_START | unsigned long * | unsigned long | Y start
VRENDER_CONTEXT_ATT_SUBCUBE_Y_END | unsigned long * | unsigned long | Y end
VRENDER_CONTEXT_ATT_SUBCUBE_Z_START | unsigned long * | unsigned long | Z start
VRENDER_CONTEXT_ATT_SUBCUBE_Z_END | unsigned long * | unsigned long | Z end
VRENDER_CONTEXT_ATT_IMAGE_DESC | array_desc * |  | Image descriptor
VRENDER_CONTEXT_ATT_VALID_IMAGE_DESC | flag * | flag | Valid image descriptor
VRENDER_CONTEXT_ATT_PROJECTION |  | unsigned int | Projection code
VRENDER_CONTEXT_ATT_EYE_SEPARATION |  | double | Distance between eyes
VRENDER_CONTEXT_ATT_SMOOTH_CACHE |  | flag | Produce smooth cache

vrender_EYES List of eye views

Name | Meaning
VRENDER_EYE_CHOICE_CYCLOPS | Single eye (monoscopic vision)
VRENDER_EYE_CHOICE_LEFT | Left eye (stereoscopic vision)
VRENDER_EYE_CHOICE_RIGHT | Right eye (stereoscopic vision)

vrender_EYE_MASKS List of eye view masks

Name | Meaning
VRENDER_EYE_MASK_CYCLOPS | Single eye (monoscopic vision)
VRENDER_EYE_MASK_LEFT | Left eye (stereoscopic vision)
VRENDER_EYE_MASK_RIGHT | Right eye (stereoscopic vision)

Back to Karma Home Page