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
- GR3_ERROR_NONE on success
- GR3_ERROR_INVALID_VALUE if one of the attributes’ values is out of the allowed range
- GR3_ERROR_INVALID_ATTRIBUTE if the list contained an unkown attribute or two mutually exclusive attributes were both used
- GR3_ERROR_OPENGL_ERR if an OpenGL error occured
- GR3_ERROR_INIT_FAILED if an error occured during initialization of the “window toolkit” (CGL, GLX, WIN…)
- 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 clearedline
: the code line the error was returned fromfile
: 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.
- OpenGL version + ” - ” + OpenGL renderer string For example “gr3 - GLX - GL_ARB_framebuffer_object - 2.1 Mesa
-
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
- GR3_ERROR_NONE on success
- GR3_ERROR_OPENGL_ERR if an OpenGL error occured
- GR3_ERROR_NOT_INITIALIZED if the function was called without calling gr3_init() first
-
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
- GR3_ERROR_NONE on success
- GR3_ERROR_OPENGL_ERR if an OpenGL error occured
- GR3_ERROR_OUT_OF_MEM if a memory allocation failed
- Parameters
mesh
: a pointer to a intvertices
: the vertex positionsnormals
: the vertex normalscolors
: the vertex colors, they should be white (1,1,1) if you want to change the color for each drawn meshn
: 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
- GR3_ERROR_NONE on success
- GR3_ERROR_OPENGL_ERR if an OpenGL error occured
- GR3_ERROR_OUT_OF_MEM if a memory allocation failed
- Parameters
mesh
: a pointer to a intvertices
: the vertex positionsnormals
: the vertex normalscolors
: the vertex colors, they should be white (1,1,1) if you want to change the color for each drawn meshn
: 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
- GR3_ERROR_NONE on success
- GR3_ERROR_OPENGL_ERR if an OpenGL error occured
- GR3_ERROR_OUT_OF_MEM if a memory allocation failed
- Parameters
mesh
: a pointer to an intnumber_of_vertices
: the number of vertices in the meshvertices
: the vertex positionsnormals
: the vertex normalscolors
: the vertex colors, they should be white (1,1,1) if you want to change the color for each drawn meshnumber_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
- GR3_ERROR_NONE on success
- GR3_ERROR_OPENGL_ERR if an OpenGL error occured
- GR3_ERROR_OUT_OF_MEM if a memory allocation failed
- Parameters
mesh
: a pointer to an intnumber_of_vertices
: the number of vertices in the meshvertices
: the vertex positionsnormals
: the vertex normalscolors
: the vertex colors, they should be white (1,1,1) if you want to change the color for each drawn meshnumber_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 drawnpositions
: The positions where the meshes should be drawndirections
: The forward directions the meshes should be facing atups
: The up directionscolors
: The colors the meshes should be drawn in, it will be multiplied with each vertex colorscales
: The scaling factorsn
: 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 cameracamera_y
: The y-coordinate of the cameracamera_z
: The z-coordinate of the cameracenter_x
: The x-coordinate of the center of focuscenter_y
: The y-coordinate of the center of focuscenter_z
: The z-coordinate of the center of focusup_x
: The x-component of the up directionup_y
: The y-component of the up directionup_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
- GR3_ERROR_NONE on success
- GR3_ERROR_INVALID_VALUE if one (or more) of the arguments is out of its range
- 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
- GR3_ERROR_NONE on success
- Parameters
vfov
: Vertical field of view in degreesznear
: 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 directiony
: The y-component of the light’s directionz
: 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) dataisolevel
: value where the isosurface will be extracteddim_x
: number of elements in x-directiondim_y
: number of elements in y-directiondim_z
: number of elements in z-directionstride_x
: number of elements to step when traversing the data in x-directionstride_y
: number of elements to step when traversing the data in y-directionstride_z
: number of elements to step when traversing the data in z-directionstep_x
: distance between the voxels in x-directionstep_y
: distance between the voxels in y-directionstep_z
: distance between the voxels in z-directionoffset_x
: coordinate originoffset_y
: coordinate originoffset_z
: coordinate origintriangles_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) dataisolevel
: value where the isosurface will be extracteddim_x
: number of elements in x-directiondim_y
: number of elements in y-directiondim_z
: number of elements in z-directionstride_x
: number of elements to step when traversing the data in x-directionstride_y
: number of elements to step when traversing the data in y-directionstride_z
: number of elements to step when traversing the data in z-directionstep_x
: distance between the voxels in x-directionstep_y
: distance between the voxels in y-directionstep_z
: distance between the voxels in z-directionoffset_x
: coordinate originoffset_y
: coordinate originoffset_z
: coordinate originnum_vertices
: number of vertices createdvertices
: array of vertex coordinatesnormals
: array of vertex normal vectorsnum_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 handlenx
: number of points in x-directionny
: number of points in y-directionpx
: an array containing the x-coordinatespy
: an array containing the y-coordinatespz
: an array of length nx * ny containing the z-coordinatesoption
: 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 drawnn
: the number of meshes to be drawnpositions
: the positions where the meshes should be drawndirections
: the forward directions the meshes should be facing atups
: the up directionscolors
: the colors the meshes should be drawn in, it will be multiplied with each vertex colorscales
: 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-directionny
: number of points in y-directionpx
: an array containing the x-coordinatespy
: an array containing the y-coordinatespz
: an array of length nx * ny containing the z-coordinatesoption
: 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 trianglespositions
: 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-directionny
: number of points in y-directionnz
: number of points in z-directiondata
: an array of shape nx * ny * nz containing the intensities for each pointalgorithm
: the algorithm to reduce the volume datadmin_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
¶
-
struct
gr3_triangle_t
¶