GR3 Reference

The gr3 header

Defines

GR3API
GR3_IA_END_OF_LIST

These constants can be used to specify various properties when calling gr3_init().This constant is used as a delimiter \ for the attribute list.

GR3_IA_FRAMEBUFFER_WIDTH

The next element of the attribute list \ will be used as the width of the \ framebuffer used for rendering. \ Default: 512

GR3_IA_FRAMEBUFFER_HEIGHT

The next element of the attribute list \ will be used as the height of the \ framebuffer used for rendering. \ Default: 512

GR3_ERROR_NONE

These contants are error codes returned by gr3 functions.The function was successful

GR3_ERROR_INVALID_VALUE

The function failed because of \ an invalid value

GR3_ERROR_INVALID_ATTRIBUTE

The function failed because of \ an invalid attribute

GR3_ERROR_INIT_FAILED

Initialization failed

GR3_ERROR_OPENGL_ERR

An OpenGL error occured

GR3_ERROR_OUT_OF_MEM

gr3 was unable to allocate \ required memory. If this error \ occurs, gr3 state is undefined.

GR3_ERROR_NOT_INITIALIZED

A function was called before \ initializing gr3.

GR3_ERROR_CAMERA_NOT_INITIALIZED

gr3_getpixmap() was called \ before initializing the camera

GR3_ERROR_UNKNOWN_FILE_EXTENSION
GR3_ERROR_CANNOT_OPEN_FILE
GR3_ERROR_EXPORT
GR3_QUALITY_OPENGL_NO_SSAA
GR3_QUALITY_OPENGL_2X_SSAA
GR3_QUALITY_OPENGL_4X_SSAA
GR3_QUALITY_OPENGL_8X_SSAA
GR3_QUALITY_OPENGL_16X_SSAA
GR3_QUALITY_POVRAY_NO_SSAA
GR3_QUALITY_POVRAY_2X_SSAA
GR3_QUALITY_POVRAY_4X_SSAA
GR3_QUALITY_POVRAY_8X_SSAA
GR3_QUALITY_POVRAY_16X_SSAA
GR3_DRAWABLE_OPENGL
GR3_DRAWABLE_GKS
GR3_MC_DTYPE
GR3_PROJECTION_PERSPECTIVE
GR3_PROJECTION_PARALLEL
GR3_SURFACE_DEFAULT

default behavior

GR3_SURFACE_NORMALS

interpolate the vertex normals \ from the gradient

GR3_SURFACE_FLAT

set all z-coordinates to zero

GR3_SURFACE_GRTRANSFORM

use gr_inqwindow, gr_inqspace \ and gr_inqscale to transform the \ data to NDC coordinates

GR3_SURFACE_GRCOLOR

color the surface according to \ the current gr colormap

GR3_SURFACE_GRZSHADED

like GR3_SURFACE_GRCOLOR, but \ use the z-value directly as \ color index

GR_VOLUME_EMISSION
GR_VOLUME_ABSORPTION
GR_VOLUME_MIP

Functions

int gr3_init(int *attrib_list)

This method initializes the gr3 context.

Return
See
gr3_terminate()
See
context_struct_
See
int
Parameters
  • attrib_list: This GR3_IA_END_OF_LIST-terminated list can specify details about context creation. The attributes which use unsigned integer values are followed by these values.

void gr3_free(void *pointer)
void gr3_terminate(void)

This function terminates the gr3 context. After calling this function, gr3 is in the same state as when it was first loaded, except for context-independent variables, i.e. the logging callback.

Note
It is safe to call this function even if the context is not initialized.
See
gr3_init()
See
context_struct_

int gr3_geterror(int clear, int *line, const char **file)

This function returns information on the most recent GR3 error.

Return
the last non-zero error code
Parameters
  • clear: 1 if the error information should be cleared
  • line: the code line the error was returned from
  • file: the code file the error was returned from

const char *gr3_getrenderpathstring(void)

This function allows the user to find out how his commands are rendered.

Return
If gr3 is initialized, a string in the format: “gr3 - ” + window toolkit + ” - ” + framebuffer extension + ” - “
  • OpenGL version + ” - ” + OpenGL renderer string For example “gr3 - GLX - GL_ARB_framebuffer_object - 2.1 Mesa

    7.10.2 - Software Rasterizer” might be returned on a Linux system (using GLX) with an available GL_ARB_framebuffer_object implementation. If gr3 is not initialized “Not initialized” is returned.

const char *gr3_geterrorstring(int error)

This function returns a string representation of a given error code.

Parameters
  • error: The error code whose represenation will be returned.

void gr3_setlogcallback(void (*gr3_log_func)(const char *log_message))

During software development it will often be helpful to get debug output from gr3. This information is not printed, but reported directly to the user by calling a logging callback. This function allows to set this callback or disable it again by calling it with NULL.

Parameters
  • gr3_log_func: The logging callback, a function which gets a const char pointer as its only argument and returns nothing.

int gr3_clear(void)

This function clears the draw list.

Return

void gr3_usecurrentframebuffer()
void gr3_useframebuffer(unsigned int framebuffer)
int gr3_setquality(int quality)
int gr3_getimage(int width, int height, int use_alpha, char *pixels)
int gr3_export(const char *filename, int width, int height)
int gr3_drawimage(float xmin, float xmax, float ymin, float ymax, int width, int height, int drawable_type)
int gr3_createmesh_nocopy(int *mesh, int n, float *vertices, float *normals, float *colors)

This function creates a mesh from vertex position, normal and color data. The arrays are used directly without copying. The array parameters MUST be pointers to the beginning of a memory region previously allocated by malloc or calloc. Changing the data in these arrays or freeing them leads to undefined behavior. After calling this routine the arrays are owned by GR3 and will be freed by it. If unsure, use gr3_createmesh.

Return
Parameters
  • mesh: a pointer to a int
  • vertices: the vertex positions
  • normals: the vertex normals
  • colors: the vertex colors, they should be white (1,1,1) if you want to change the color for each drawn mesh
  • n: the number of vertices in the mesh

int gr3_createmesh(int *mesh, int n, const float *vertices, const float *normals, const float *colors)

This function creates a int from vertex position, normal and color data.

Return
Parameters
  • mesh: a pointer to a int
  • vertices: the vertex positions
  • normals: the vertex normals
  • colors: the vertex colors, they should be white (1,1,1) if you want to change the color for each drawn mesh
  • n: the number of vertices in the mesh

int gr3_createindexedmesh_nocopy(int *mesh, int number_of_vertices, float *vertices, float *normals, float *colors, int number_of_indices, int *indices)

This function creates an indexed mesh from vertex information (position, normal and color) and triangle information (indices). The arrays are used directly without copying. The array parameters MUST be pointers to the beginning of a memory region previously allocated by malloc or calloc. Changing the data in these arrays or freeing them leads to undefined behavior. After calling this routine the arrays are owned by GR3 and will be freed by it. If unsure, use gr3_createindexedmesh.

Return
Parameters
  • mesh: a pointer to an int
  • number_of_vertices: the number of vertices in the mesh
  • vertices: the vertex positions
  • normals: the vertex normals
  • colors: the vertex colors, they should be white (1,1,1) if you want to change the color for each drawn mesh
  • number_of_indices: the number of indices in the mesh (three times the number of triangles)
  • indices: the index array (vertex indices for each triangle)

int gr3_createindexedmesh(int *mesh, int number_of_vertices, const float *vertices, const float *normals, const float *colors, int number_of_indices, const int *indices)

This function creates an indexed mesh from vertex information (position, normal and color) and triangle information (indices).

Return
Parameters
  • mesh: a pointer to an int
  • number_of_vertices: the number of vertices in the mesh
  • vertices: the vertex positions
  • normals: the vertex normals
  • colors: the vertex colors, they should be white (1,1,1) if you want to change the color for each drawn mesh
  • number_of_indices: the number of indices in the mesh (three times the number of triangles)
  • indices: the index array (vertex indices for each triangle)

void gr3_drawmesh(int mesh, int n, const float *positions, const float *directions, const float *ups, const float *colors, const float *scales)

This function adds a mesh to the draw list, so it will be drawn when the user calls gr3_getpixmap_(). The given data stays owned by the user, a copy will be saved in the draw list and the mesh reference counter will be increased.

Note
This function does not return an error code, because of its asynchronous nature. If gr3_getpixmap_() returns a GR3_ERROR_OPENGL_ERR, this might be caused by this function saving unuseable data into the draw list.
Parameters
  • mesh: The mesh to be drawn
  • positions: The positions where the meshes should be drawn
  • directions: The forward directions the meshes should be facing at
  • ups: The up directions
  • colors: The colors the meshes should be drawn in, it will be multiplied with each vertex color
  • scales: The scaling factors
  • n: The number of meshes to be drawn

void gr3_deletemesh(int mesh)

This function marks a mesh for deletion and removes the user’s reference from the mesh’s referenc counter, so a user must not use the mesh after calling this function. If the mesh is still in use for draw calls, the mesh will not be truly deleted until gr3_clear() is called.

Parameters
  • mesh: The mesh that should be marked for deletion

void gr3_cameralookat(float camera_x, float camera_y, float camera_z, float center_x, float center_y, float center_z, float up_x, float up_y, float up_z)

This function sets the view matrix by getting the position of the camera, the position of the center of focus and the direction which should point up. This function takes effect when the next image is created. Therefore if you want to take pictures of the same data from different perspectives, you can call and gr3_cameralookat(), gr3_getpixmap_(), gr3_cameralookat(), gr3_getpixmap_(), … without calling gr3_clear() and gr3_drawmesh() again.

Note
Source: http://www.opengl.org/sdk/docs/man/xhtml/gluLookAt.xml (as of 10/24/2011, licensed under SGI Free Software Licence B)
Parameters
  • camera_x: The x-coordinate of the camera
  • camera_y: The y-coordinate of the camera
  • camera_z: The z-coordinate of the camera
  • center_x: The x-coordinate of the center of focus
  • center_y: The y-coordinate of the center of focus
  • center_z: The z-coordinate of the center of focus
  • up_x: The x-component of the up direction
  • up_y: The y-component of the up direction
  • up_z: The z-component of the up direction

int gr3_setcameraprojectionparameters(float vertical_field_of_view, float zNear, float zFar)

This function sets the projection parameters. This function takes effect when the next image is created.

Return
Note
The ratio between zFar and zNear influences the precision of the depth buffer, the greater \( \frac{zFar}{zNear} \), the more likely are errors. So you should try to keep both values as close to each other as possible while making sure everything you want to be visible, is visible.
Parameters
  • vertical_field_of_view: This parameter is the vertical field of view in degrees. It must be greater than 0 and less than 180.
  • zNear: The distance to the near clipping plane.
  • zFar: The distance to the far clipping plane.

int gr3_getcameraprojectionparameters(float *vfov, float *znear, float *zfar)

Get the projection parameters.

Return
Parameters
  • vfov: Vertical field of view in degrees
  • znear: The distance to the near clipping plane.
  • zfar: The distance to the far clipping plane.

void gr3_setlightdirection(float x, float y, float z)

This function sets the direction of light. If it is called with (0, 0, 0), the light is always pointing into the same direction as the camera.

Parameters
  • x: The x-component of the light’s direction
  • y: The y-component of the light’s direction
  • z: The z-component of the light’s direction

void gr3_setbackgroundcolor(float red, float green, float blue, float alpha)

This function sets the background color.

int gr3_createheightmapmesh(const float *heightmap, int num_columns, int num_rows)
void gr3_drawheightmap(const float *heightmap, int num_columns, int num_rows, const float *positions, const float *scales)
void gr3_drawconemesh(int n, const float *positions, const float *directions, const float *colors, const float *radii, const float *lengths)
void gr3_drawcylindermesh(int n, const float *positions, const float *directions, const float *colors, const float *radii, const float *lengths)
void gr3_drawspheremesh(int n, const float *positions, const float *colors, const float *radii)
void gr3_drawcubemesh(int n, const float *positions, const float *directions, const float *ups, const float *colors, const float *scales)
void gr3_setobjectid(int id)
int gr3_selectid(int x, int y, int width, int height, int *selection_id)
void gr3_getviewmatrix(float *m)

Parameters
  • m: the 4x4 column major view matrix

void gr3_setviewmatrix(const float *m)

Parameters
  • m: the 4x4 column major view matrix

int gr3_getprojectiontype(void)

Return
the current projection type: GR3_PROJECTION_PERSPECTIVE or GR3_PROJECTION_PARALLEL

void gr3_setprojectiontype(int type)

Parameters
  • type: the new projection type: GR3_PROJECTION_PERSPECTIVE or GR3_PROJECTION_PARALLEL

unsigned int gr3_triangulate(const GR3_MC_DTYPE *data, GR3_MC_DTYPE isolevel, unsigned int dim_x, unsigned int dim_y, unsigned int dim_z, unsigned int stride_x, unsigned int stride_y, unsigned int stride_z, double step_x, double step_y, double step_z, double offset_x, double offset_y, double offset_z, gr3_triangle_t **triangles_p)

Create an isosurface (as mesh) from voxel data with the marching cubes algorithm. This function calls gr3_triangulateindexed and copies the values.

Return
the number of triangles created
Parameters
  • data: the volume (voxel) data
  • isolevel: value where the isosurface will be extracted
  • dim_x: number of elements in x-direction
  • dim_y: number of elements in y-direction
  • dim_z: number of elements in z-direction
  • stride_x: number of elements to step when traversing the data in x-direction
  • stride_y: number of elements to step when traversing the data in y-direction
  • stride_z: number of elements to step when traversing the data in z-direction
  • step_x: distance between the voxels in x-direction
  • step_y: distance between the voxels in y-direction
  • step_z: distance between the voxels in z-direction
  • offset_x: coordinate origin
  • offset_y: coordinate origin
  • offset_z: coordinate origin
  • triangles_p: array of triangle data

void gr3_triangulateindexed(const GR3_MC_DTYPE *data, GR3_MC_DTYPE isolevel, unsigned int dim_x, unsigned int dim_y, unsigned int dim_z, unsigned int stride_x, unsigned int stride_y, unsigned int stride_z, double step_x, double step_y, double step_z, double offset_x, double offset_y, double offset_z, unsigned int *num_vertices, gr3_coord_t **vertices, gr3_coord_t **normals, unsigned int *num_indices, unsigned int **indices)

Create an isosurface (as indexed mesh) from voxel data with the marching cubes algorithm. This function manages the parallelization: Divide the data into blocks along the x-axis. Allocate memory, call layerblock and merge the individual meshes into a single one.

Parameters
  • data: the volume (voxel) data
  • isolevel: value where the isosurface will be extracted
  • dim_x: number of elements in x-direction
  • dim_y: number of elements in y-direction
  • dim_z: number of elements in z-direction
  • stride_x: number of elements to step when traversing the data in x-direction
  • stride_y: number of elements to step when traversing the data in y-direction
  • stride_z: number of elements to step when traversing the data in z-direction
  • step_x: distance between the voxels in x-direction
  • step_y: distance between the voxels in y-direction
  • step_z: distance between the voxels in z-direction
  • offset_x: coordinate origin
  • offset_y: coordinate origin
  • offset_z: coordinate origin
  • num_vertices: number of vertices created
  • vertices: array of vertex coordinates
  • normals: array of vertex normal vectors
  • num_indices: number of indices created (3 times the number of triangles)
  • indices: array of vertex indices that make the triangles

int gr3_createisosurfacemesh(int *mesh, GR3_MC_DTYPE *data, GR3_MC_DTYPE isolevel, unsigned int dim_x, unsigned int dim_y, unsigned int dim_z, unsigned int stride_x, unsigned int stride_y, unsigned int stride_z, double step_x, double step_y, double step_z, double offset_x, double offset_y, double offset_z)
int gr3_createsurfacemesh(int *mesh, int nx, int ny, float *px, float *py, float *pz, int option)

Create a mesh of a surface plot similar to gr_surface. Uses the current colormap. To apply changes of the colormap a new mesh has to be created.

Parameters
  • mesh: the mesh handle
  • nx: number of points in x-direction
  • ny: number of points in y-direction
  • px: an array containing the x-coordinates
  • py: an array containing the y-coordinates
  • pz: an array of length nx * ny containing the z-coordinates
  • option: option for the surface mesh; the GR3_SURFACE constants can be combined with bitwise or.

void gr3_drawmesh_grlike(int mesh, int n, const float *positions, const float *directions, const float *ups, const float *colors, const float *scales)

Draw a mesh with the projection of gr. It uses the current projection parameters (rotation, tilt) of gr. This function alters the projection type, the projection parameters, the viewmatrix and the light direction. If necessary, the user has to save them before the call to this function and restore them after the call to gr3_drawimage.

Parameters
  • mesh: the mesh to be drawn
  • n: the number of meshes to be drawn
  • positions: the positions where the meshes should be drawn
  • directions: the forward directions the meshes should be facing at
  • ups: the up directions
  • colors: the colors the meshes should be drawn in, it will be multiplied with each vertex color
  • scales: the scaling factors

void gr3_drawsurface(int mesh)

Convenience function for drawing a surfacemesh

Parameters
  • mesh: the mesh to be drawn

void gr3_surface(int nx, int ny, float *px, float *py, float *pz, int option)

Create a surface plot with gr3 and draw it with gks as cellarray

Parameters
  • nx: number of points in x-direction
  • ny: number of points in y-direction
  • px: an array containing the x-coordinates
  • py: an array containing the y-coordinates
  • pz: an array of length nx * ny containing the z-coordinates
  • option: see the option parameter of gr_surface

int gr3_drawtubemesh(int n, float *points, float *colors, float *radii, int num_steps, int num_segments)
int gr3_createtubemesh(int *mesh, int n, const float *points, const float *colors, const float *radii, int num_steps, int num_segments)
void gr3_drawspins(int n, const float *positions, const float *directions, const float *colors, float cone_radius, float cylinder_radius, float cone_height, float cylinder_height)
void gr3_drawmolecule(int n, const float *positions, const float *colors, const float *radii, float bond_radius, const float bond_color[3], float bond_delta)
void gr3_createxslicemesh(int *mesh, const GR3_MC_DTYPE *data, unsigned int ix, unsigned int dim_x, unsigned int dim_y, unsigned int dim_z, unsigned int stride_x, unsigned int stride_y, unsigned int stride_z, double step_x, double step_y, double step_z, double offset_x, double offset_y, double offset_z)
void gr3_createyslicemesh(int *mesh, const GR3_MC_DTYPE *data, unsigned int iy, unsigned int dim_x, unsigned int dim_y, unsigned int dim_z, unsigned int stride_x, unsigned int stride_y, unsigned int stride_z, double step_x, double step_y, double step_z, double offset_x, double offset_y, double offset_z)
void gr3_createzslicemesh(int *mesh, const GR3_MC_DTYPE *data, unsigned int iz, unsigned int dim_x, unsigned int dim_y, unsigned int dim_z, unsigned int stride_x, unsigned int stride_y, unsigned int stride_z, double step_x, double step_y, double step_z, double offset_x, double offset_y, double offset_z)
void gr3_drawxslicemesh(const GR3_MC_DTYPE *data, unsigned int ix, unsigned int dim_x, unsigned int dim_y, unsigned int dim_z, unsigned int stride_x, unsigned int stride_y, unsigned int stride_z, double step_x, double step_y, double step_z, double offset_x, double offset_y, double offset_z)
void gr3_drawyslicemesh(const GR3_MC_DTYPE *data, unsigned int iy, unsigned int dim_x, unsigned int dim_y, unsigned int dim_z, unsigned int stride_x, unsigned int stride_y, unsigned int stride_z, double step_x, double step_y, double step_z, double offset_x, double offset_y, double offset_z)
void gr3_drawzslicemesh(const GR3_MC_DTYPE *data, unsigned int iz, unsigned int dim_x, unsigned int dim_y, unsigned int dim_z, unsigned int stride_x, unsigned int stride_y, unsigned int stride_z, double step_x, double step_y, double step_z, double offset_x, double offset_y, double offset_z)
void gr3_drawtrianglesurface(int n, const float *triangles)

Draw the given triangles using the current GR colormap

Parameters
  • n: number of triangles
  • positions: pointer to an array of 3*3*n float values

void gr_volume(int nx, int ny, int nz, double *data, int algorithm, double *dmin_ptr, double *dmax_ptr)

Draw volume data using the given algorithm and apply the current GR colormap.

Available algorithms are:

GR_VOLUME_EMISSION 0 emission model
GR_VOLUME_ABSORPTION 1 absorption model
GR_VOLUME_MIP 2 maximum intensity projection
Parameters
  • nx: number of points in x-direction
  • ny: number of points in y-direction
  • nz: number of points in z-direction
  • data: an array of shape nx * ny * nz containing the intensities for each point
  • algorithm: the algorithm to reduce the volume data
  • dmin_ptr: The variable this parameter points at will be used as minimum data value when applying the colormap. If it is negative, the variable will be set to the actual occuring minimum and that value will be used instead. If dmin_ptr is NULL, it will be ignored.
  • dmax_ptr: The variable this parameter points at will be used as maximum data value when applying the colormap. If it is negative, the variable will be set to the actual occuring maximum and that value will be used instead. If dmax_ptr is NULL, it will be ignored.

struct gr3_coord_t

Public Members

float x
float y
float z
struct gr3_triangle_t

Public Members

gr3_coord_t vertex[3]
gr3_coord_t normal[3]