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_contextCreate a context for volume rendering.
vrender_set_context_attributesSet the attributes for a volume rendering context.
vrender_get_context_attributesGet the attributes for a volume rendering context.
vrender_register_shaderRegister a shader function.
vrender_change_shader_blank_packetChange blank value for a particular shader.
vrender_get_shadersGet the names of all registered shaders.
vrender_to_bufferRender a scene in a volume rendering context to a buffer.
vrender_collect_rayCollect a ray projected from an image plane into a volume.
vrender_project_3dProject a point in 3-dimensional space onto a view plane.
vrender_compute_cachesCompute cache for volume rendering context.
vrender_image_desc_notify_funcRegister image descriptor change callback.
vrender_cache_notify_funcRegister cache computed callback.
vrender_view_notify_funcRegister view changed computed callback.
vrender_message_notify_funcRegister message callback.
vrender_client_notify_funcRegister new client callback.
vrender_get_eye_infoGet eye information.
vrender_show_statsShow distributed rendering statistics.
vrender_send_messageSend a message to all "VRENDER_private" clients.

Prototype Functions

vrender_PROTO_render_notify_funcVolume rendering completed callback.
vrender_PROTO_image_desc_notify_funcImage descriptor changed callback.
vrender_PROTO_cache_notify_funcCache computed callback.
vrender_PROTO_view_notify_funcView changed callback.
vrender_PROTO_message_notify_funcMessage received callback.
vrender_PROTO_client_notify_funcClient connected callback.

Tables

vrender_ATTRIBUTESList of attributes volume rendering contexts
vrender_EYESList of eye views
vrender_EYE_MASKSList of eye view masks


Functions


KVolumeRenderContext vrender_create_context (void *info, ...)

Create a context for volume rendering.

Parameters:

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:

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:

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:

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:

Returns: Nothing.
Multithreading Level: Unsafe


CONST char ** vrender_get_shaders (unsigned int *num_shaders)

Get the names of all registered shaders.

Parameters:

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:

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


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:

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:

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:

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:

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:

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:

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:

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:

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:

Returns: Nothing.
Multithreading Level: Unsafe


EXPERIMENTAL FUNCTION: subject to change without notice

void vrender_show_stats (KVolumeRenderContext context)

Show distributed rendering statistics.

Parameters:

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:

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:

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:

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:

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:

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:

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:

Returns: Nothing.
Multithreading Level: Unsafe


Tables


vrender_ATTRIBUTES

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

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

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
Contact: Richard Gooch
Web Development: Ariel Internet Services