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)

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

Contact: Richard Gooch
Web Development: Ariel Internet Services

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

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)

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)