ruby-gr 0.0.23 → 0.58.1.0

data/lib/gr3.rb

@@ -40,39 +40,54 @@
 #
 # Fiddley is Ruby-FFI compatible API layer for Fiddle.
 #
-# Why not GR::GR3?
-# * kojix2 did not want to force gr3 to be loaded when gr is loaded.
-# * kojix2 did not want to write `GR3 = GR::GR3` or something.
-# * This is a opinion of kojix2 and may be changed by future maintainers.
+# @note
+#   Why not GR::GR3?
+#   * kojix2 did not want to force gr3 to be loaded when gr is loaded.
+#   * kojix2 did not want to write `GR3 = GR::GR3` or something.
+#   * This is a opinion of kojix2 and may be changed by future maintainers.
 #
-# GR3 uses Numo::Narrray.
-# * It is difficult to write GR3 modules with only Ruby arrays.
-# * Numo::Narray has better performance and is easier to read.
-# * Numo::Narray does not work with JRuby.
-#   * https://github.com/ruby-numo/numo-narray/issues/147
+# @note
+#   GR3 uses Numo::Narrray.
+#   * It is difficult to write GR3 modules with only Ruby arrays.
+#   * Numo::Narray has better performance and is easier to read.
+#   * Numo::Narray does not work with JRuby.
+#     * https://github.com/ruby-numo/numo-narray/issues/147
 #
 # This is a procedural interface to the GR3 in GR plotting library,
 # https://github.com/sciapp/gr
 module GR3
   class Error < StandardError; end
 
+  class NotFoundError < Error; end
+
   class << self
     attr_accessor :ffi_lib
   end
 
   require_relative 'gr_commons/gr_commons'
-  extend GRCommons::SearchSharedLibrary
 
   # Platforms |  path
   # Windows   |  bin/libGR3.dll
-  # MacOSX    |  lib/libGR3.so (NOT .dylib)
+  # MacOSX    |  lib/libGR3.dylib ( <= v0.53.0 .so)
   # Ubuntu    |  lib/libGR3.so
-  self.ffi_lib = case RbConfig::CONFIG['host_os']
-                 when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
-                   search_shared_library('libGR3.dll', 'gr3')
-                 else
-                   search_shared_library('libGR3.so', 'gr3')
-                 end
+  platform = RbConfig::CONFIG['host_os']
+  lib_names, pkg_name = \
+    case platform
+    when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+      [['libGR3.dll'], 'gr3']
+    when /darwin|mac os/
+      [['libGR3.dylib', 'libGR3.so'], 'gr3']
+    else
+      [['libGR3.so'], 'gr3']
+    end
+
+  # On Windows + RubyInstaller,
+  # the environment variable GKS_FONTPATH will be set.
+  lib_path = GRCommons::GRLib.search(lib_names, pkg_name)
+
+  raise NotFoundError, "#{lib_names} not found" if lib_path.nil?
+
+  self.ffi_lib = lib_path
 
   require_relative 'gr3/version'
   require_relative 'gr3/ffi'
@@ -117,70 +132,82 @@ module GR3
   end
   extend CheckError
 
-  # Now you can see a lot of methods just calling super here.
-  # They are written to help the yard generate the documentation.
   class << self
     # This method initializes the gr3 context.
+    #
     # @return [Integer]
-    def gr3_init(*)
-      super
-    end
+    #
+    # @!method gr3_init
 
-    def free(*)
-      super
-    end
+    # @!method free
 
     # This function terminates the gr3 context.
-    def terminate(*)
-      super
-    end
+    #
+    # 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.
+    #
+    # @!method terminate
 
-    # @!method geterror
+    # @note This method is defined in the CheckError module.
+    #
     # This function returns information on the most recent GR3 error.
+    #
     # @return [Integer]
-    # @note This method is defined in the CheckError module.
+    #
+    # @!method geterror
 
     # This function allows the user to find out how his commands are rendered.
+    #
     # 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.
+    # `"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.
+    #
     # @return [String]
+    #
     def getrenderpathstring(*)
       super.to_s
     end
 
     # This function returns a string representation of a given error code.
+    #
     # @return [String]
+    #
     def geterrorstring(*)
       super.to_s
     end
 
     # This function clears the draw list.
+    #
     # @return [Integer]
-    def clear(*)
-      super
-    end
+    #
+    # @!method clear
 
-    # Use the currently bound framebuffer as the framebuffer used for drawing to OpenGL (using gr3.drawimage).
-    # This function is only needed when you do not want to render to 0, the default framebuffer.
-    def usecurrentframebuffer(*)
-      super
-    end
+    # Use the currently bound framebuffer as the framebuffer used for drawing to
+    # OpenGL (using gr3.drawimage).
+    # This function is only needed when you do not want to render to 0, the
+    # default framebuffer.
+    #
+    # @!method usecurrentframebuffer
 
     # Set the framebuffer used for drawing to OpenGL (using gr3.drawimage).
-    # This function is only needed when you do not want to render to 0, the default framebuffer.
-    def useframebuffer(*)
-      super
-    end
+    #
+    # This function is only needed when you do not want to render to 0, the
+    # default framebuffer.
+    #
+    # @!method useframebuffer
 
     # Set rendering quality
+    #
     # @param quality [] The quality to set
+    #
     # @return [Integer]
-    def setquality(*)
-      super
-    end
+    #
+    # @!method setquality
 
     # @return [Integer]
     def getimage(width, height, use_alpha = true)
@@ -191,31 +218,31 @@ module GR3
     end
 
     # @return [Integer]
-    def export(*)
-      super
-    end
+    # @!method export
 
     # @return [Integer]
-    def drawimage(*)
-      super
-    end
+    # @!method drawimage
 
-    # createmesh_nocopy
+    # This function creates a mesh from vertex position, normal and color data.
+    #
     # @return [Integer]
-    def createmesh_nocopy(_n, vertices, normals, colors)
+    def createmesh_nocopy(n, vertices, normals, colors)
       inquiry_int do |mesh|
-        super(mesh, vertices, normals, colors)
+        super(mesh, n, vertices, normals, colors)
       end
     end
 
     # This function creates a int from vertex position, normal and color data.
     # Returns a mesh.
-    # @param n [Integer] the number of vertices in the mesh
+    #
+    # @param n        [Integer]       the number of vertices in the mesh
     # @param vertices [Array, NArray] the vertex positions
-    # @param normals [Array, NArray] the vertex normals
-    # @param colors [Array, NArray] the vertex colors,
-    #  they should be white (1,1,1) if you want to change the color for each drawn mesh
+    # @param normals  [Array, NArray] the vertex normals
+    # @param colors   [Array, NArray] the vertex colors, they should be
+    #   white (1,1,1) if you want to change the color for each drawn mesh
+    #
     # @return [Integer]
+    #
     def createmesh(n, vertices, normals, colors)
       inquiry_int do |mesh|
         super(mesh, n, vertices, normals, colors)
@@ -223,6 +250,7 @@ module GR3
     end
 
     # This function creates a mesh from vertex position, normal and color data.
+    #
     # @return [Integer]
     def createindexedmesh_nocopy(num_vertices, vertices, normals, colors, num_indices, indices)
       inquiry_int do |mesh|
@@ -233,150 +261,159 @@ module GR3
     # This function creates an indexed mesh from vertex information (position,
     # normal and color) and triangle information (indices).
     # Returns a mesh.
-    # @param num_vertices [Integer] the number of vertices in the mesh
-    # @param vertices [Array, NArray] the vertex positions
-    # @param normals [Array, NArray] the vertex normals
-    # @param colors [Array, NArray] the vertex colors,
-    #  they should be white (1,1,1) if you want to change the color for each drawn mesh
-    # @param num_indices [Integer] the number of indices in the mesh (three times the number of triangles)
-    # @param indices [Array, NArray] the index array (vertex indices for each triangle)
+    #
+    # @param num_vertices [Integer]       the number of vertices in the mesh
+    # @param vertices     [Array, NArray] the vertex positions
+    # @param normals      [Array, NArray] the vertex normals
+    # @param colors       [Array, NArray] the vertex colors, they should be
+    #                                     white (1,1,1) if you want to change
+    #                                     the color for each drawn mesh
+    # @param num_indices  [Integer]       the number of indices in the mesh
+    #                                     (three times the number of triangles)
+    # @param indices      [Array, NArray] the index array (vertex indices for
+    #                                     each triangle)
+    #
     # @return [Integer]
+    #
     def createindexedmesh(num_vertices, vertices, normals, colors, num_indices, indices)
       inquiry_int do |mesh|
         super(mesh, num_vertices, vertices, normals, colors, num_indices, indices)
       end
     end
 
-    # This function adds a mesh to the draw list, so it will be drawn when the user calls 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.
-    # @param mesh [Integer] The mesh to be drawn
-    # @param n [Integer] The number of meshes to be drawn
-    # @param positions [Array, NArray] The positions where the meshes should be drawn
+    # This function adds a mesh to the draw list, so it will be drawn when the
+    # user calls 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.
+    #
+    # 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.
+    #
+    # @param mesh       [Integer]       The mesh to be drawn
+    # @param n          [Integer]       The number of meshes to be drawn
+    # @param positions  [Array, NArray] The positions where the meshes should be drawn
     # @param directions [Array, NArray] The forward directions the meshes should be facing at
-    # @param ups [Array, NArray] The up directions
-    # @param colors [Array, NArray] The colors the meshes should be drawn in, it will be multiplied with each vertex color
-    # @param scales [Array, NArray] The scaling factors
-    def drawmesh(*)
-      super
-    end
-
-    # 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.
+    # @param ups        [Array, NArray] The up directions
+    # @param colors     [Array, NArray] The colors the meshes should be drawn in,
+    #                                   it will be multiplied with each vertex color
+    # @param scales     [Array, NArray] The scaling factors
+    #
+    # @!method drawmesh
+
+    # 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.
+    #
     # @param mesh [Integer] The mesh that should be marked for deletion
-    def deletemesh(*)
-      super
-    end
+    #
+    # @!method deletemesh
 
     # 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.
+    #
     # @param  camera_x [Array, NArray] The x-coordinate of the camera
     # @param  camera_y [Array, NArray] The y-coordinate of the camera
     # @param  camera_z [Array, NArray] The z-coordinate of the camera
     # @param  center_x [Array, NArray] The x-coordinate of the center of focus
     # @param  center_y [Array, NArray] The y-coordinate of the center of focus
     # @param  center_z [Array, NArray] The z-coordinate of the center of focus
-    # @param  up_x [Array, NArray] The x-component of the up direction
-    # @param  up_y [Array, NArray] The y-component of the up direction
-    # @param  up_z [Array, NArray] The z-component of the up direction
-    def cameralookat(*)
-      super
-    end
+    # @param  up_x     [Array, NArray] The x-component of the up direction
+    # @param  up_y     [Array, NArray] The y-component of the up direction
+    # @param  up_z     [Array, NArray] The z-component of the up direction
+    #
+    # @!method cameralookat
 
     # This function sets the projection parameters.
     # This function takes effect when the next image is created.
-    # @param vertical_field_of_view [Numeric] This parameter is the vertical field of view in degrees.
-    #  It must be greater than 0 and less than 180.
+    #
+    # The ratio between zFar and zNear influences the precision of the depth
+    # buffer, the greater (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.
+    #
+    # @param vertical_field_of_view [Numeric]
+    #   This parameter is the vertical field of view in degrees.
+    #   It must be greater than 0 and less than 180.
     # @param zNear [Numeric] The distance to the near clipping plane.
-    # @param zFar [Numeric] The distance to the far clipping plane.
+    # @param zFar  [Numeric] The distance to the far clipping plane.
+    #
     # @return [Integer]
-    def setcameraprojectionparameters(*)
-      super
-    end
+    #
+    # @!method setcameraprojectionparameters
 
     # Get the projection parameters.
+    #
+    # @param vfov  [Array, NArray] Vertical field of view in degrees
+    # @param znear [Array, NArray] The distance to the near clipping plane.
+    # @param zfar  [Array, NArray] The distance to the far clipping plane.
+    #
     # @return [Integer]
-    def getcameraprojectionparameters(*)
-      super
-    end
+    #
+    # @!method getcameraprojectionparameters
 
-    # 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.
+    # 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.
+    #
     # @param x [Numeric] The x-component of the light's direction
     # @param y [Numeric] The y-component of the light's direction
     # @param z [Numeric] The z-component of the light's direction
-    def setlightdirection(*)
-      super
-    end
+    #
+    # @!method setlightdirection
 
     # This function sets the background color.
-    def setbackgroundcolor(*)
-      super
-    end
+    # @!method setbackgroundcolor
 
     # @return [Integer]
-    def createheightmapmesh(*)
-      super
-    end
+    # @!method createheightmapmesh
 
-    def drawheightmap(*)
-      super
-    end
+    # @!method drawheightmap
 
     # This function allows drawing a cylinder without requiring a mesh.
-    def drawconemesh(*)
-      super
-    end
+    # @!method drawconemesh
 
     # This function allows drawing a cylinder without requiring a mesh.
-    def drawcylindermesh(*)
-      super
-    end
+    # @!method drawcylindermesh
 
     # This function allows drawing a sphere without requiring a mesh.
-    def drawspheremesh(*)
-      super
-    end
+    # @!method drawspheremesh
 
-    def drawcubemesh(*)
-      super
-    end
+    # @!method drawcubemesh
 
-    def setobjectid(*)
-      super
-    end
+    # @!method setobjectid
 
     # @return [Integer]
-    def selectid(*)
-      super
-    end
+    # @!method selectid
 
-    def getviewmatrix(*)
-      super
-    end
+    # @param m [Array, NArray] the 4x4 column major view matrix
+    # @!method getviewmatrix
 
-    def setviewmatrix(*)
-      super
-    end
+    # @param m [Array, NArray] the 4x4 column major view matrix
+    # @!method setviewmatrix
 
-    # the current projection type: GR3_PROJECTION_PERSPECTIVE or GR3_PROJECTION_PARALLEL
     # @return [Integer]
-    def getprojectiontype(*)
-      super
-    end
+    #   the current projection type: GR3_PROJECTION_PERSPECTIVE or GR3_PROJECTION_PARALLEL
+    # @!method getprojectiontype
 
-    # @param type [Integer] the new projection type: GR3_PROJECTION_PERSPECTIVE or GR3_PROJECTION_PARALLEL
-    def setprojectiontype(*)
-      super
-    end
+    # @param type [Integer]
+    #   the new projection type: GR3_PROJECTION_PERSPECTIVE,
+    #   GR3_PROJECTION_PARALLEL or GR3_PROJECTION_ORTHOGRAPHIC
+    # @!method setprojectiontype
 
     # This function creates an isosurface from voxel data using the
     # marching cubes algorithm.
     # Returns a mesh.
-    # @param grid [NArray] 3D narray array containing the voxel data
-    # @param step [Array] voxel sizes in each direction
-    # @param offset [Array] coordinate origin in each direction
-    # @param isolevel [Integer] isovalue at which the surface will be created
+    #
+    # @param grid     [NArray]        3D narray array containing the voxel data
+    # @param step     [Array, NArray] voxel sizes in each direction
+    # @param offset   [Array, NArray] coordinate origin in each direction
+    # @param isolevel [Integer]       isovalue at which the surface will be created
+    #
     # @return [Integer]
+    #
     def createisosurfacemesh(grid, step, offset, isolevel)
       args = _preprocess_createslicemesh(grid, step, offset)
       grid = args.shift
@@ -388,10 +425,11 @@ module GR3
     # 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.
-    # @param nx [Integer] number of points in x-direction
-    # @param ny [Integer] number of points in y-direction
-    # @param x [Array, NArray] an array containing the x-coordinates
-    # @param y [Array, NArray] an array containing the y-coordinates
+    #
+    # @param nx       [Integer] number of points in x-direction
+    # @param ny       [Integer] number of points in y-direction
+    # @param x  [Array, NArray] an array containing the x-coordinates
+    # @param y  [Array, NArray] an array containing the y-coordinates
     # @param z  [Array, NArray] an array of length nx * ny containing the z-coordinates
     # @param option [Integer] option for the surface mesh; the GR3_SURFACE constants can be combined with bitwise or. See the table below.
     #  * 0  : GR3_SURFACE_DEFAULT
@@ -406,6 +444,7 @@ module GR3
     #    *    color the surface according to the current gr colormap
     #  * 16 : GR3_SURFACE_GRZSHADED
     #    *    like GR3_SURFACE_GRCOLOR, but use the z-value directly as color index
+    #
     # @return [Integer]
     def createsurfacemesh(nx, ny, x, y, z, option = 0)
       inquiry_int do |mesh|
@@ -419,29 +458,32 @@ module GR3
     # 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.
-    # @param mesh [Integer] the mesh to be drawn
-    # @param n [Integer] the number of meshes to be drawn
-    # @param positions [Array, NArray] the positions where the meshes should be drawn
+    #
+    # @param mesh             [Integer] the mesh to be drawn
+    # @param n                [Integer] the number of meshes to be drawn
+    # @param positions  [Array, NArray] the positions where the meshes should be drawn
     # @param directions [Array, NArray] the forward directions the meshes should be facing at
-    # @param ups [Array, NArray] the up directions
-    # @param colors [Array, NArray] the colors the meshes should be drawn in, it will be multiplied with each vertex color
-    # @param scales [Array, NArray] the scaling factors
-    def drawmesh_grlike(*)
-      super
-    end
+    # @param ups        [Array, NArray] the up directions
+    # @param colors     [Array, NArray] the colors the meshes should be drawn in,
+    #                                   it will be multiplied with each vertex color
+    # @param scales     [Array, NArray] the scaling factors
+    #
+    # @!method drawmesh_grlike
 
     # Convenience function for drawing a surfacemesh.
+    #
     # @param mesh [Integer] the mesh to be drawn
-    def drawsurface(*)
-      super
-    end
+    #
+    # @!method drawsurface
 
     # Create a surface plot with gr3 and draw it with gks as cellarray.
-    # @param x [Array, NArray] an array containing the x-coordinates
-    # @param y [Array, NArray] an array containing the y-coordinates
-    # @param z  [Array, NArray] an array of length nx * ny containing the z-coordinates
-    # @param option [Integer] see the option parameter of gr_surface.
-    #  OPTION_COLORED_MESH and OPTION_Z_SHADED_MESH are supported.
+    #
+    # @param x      [Array, NArray] an array containing the x-coordinates
+    # @param y      [Array, NArray] an array containing the y-coordinates
+    # @param z      [Array, NArray] an array of length nx * ny containing the z-coordinates
+    # @param option       [Integer] see the option parameter of gr_surface.
+    #                OPTION_COLORED_MESH and OPTION_Z_SHADED_MESH are supported.
+    #
     def surface(x, y, z, option)
       nx = x.length
       ny = y.length
@@ -449,17 +491,20 @@ module GR3
       super(nx, ny, x, y, z, option)
     end
 
-    # drawtubemesh
     # Draw a tube following a path given by a list of points. The colors and
     # radii arrays specify the color and radius at each point.
-    # @param n [Integer] the number of points given
+    #
+    # @param n            [Integer] the number of points given
     # @param points [Array, NArray] the points the tube should go through
     # @param colors [Array, NArray] the color at each point
-    # @param radii [Array, NArray]  the desired tube radius at each point
-    # @param num_steps [Integer] the number of steps between each point, allowing for a more smooth tube
-    # @param num_segments [Integer] the number of segments each ring of the tube consists of,
-    #  e.g. 3 would yield a triangular tube
+    # @param radii  [Array, NArray] the desired tube radius at each point
+    # @param num_steps    [Integer] the number of steps between each point,
+    #                               allowing for a more smooth tube
+    # @param num_segments [Integer] the number of segments each ring of the tube
+    #                               consists of, e.g. 3 would yield a triangular tube
+    #
     # @return [Integer]
+    #
     def drawtubemesh(n, points, colors, radii, num_steps = 10, num_segments = 20)
       super(n, points, colors, radii, num_steps, num_segments)
     end
@@ -467,12 +512,17 @@ module GR3
     # Create a mesh object in the shape of a tube following a path given by a
     # list of points. The colors and radii arrays specify the color and radius at
     # each point.
-    # @param n [Integer] the number of points given
-    # @param points [Array, NArray] the points the tube should go through
-    # @param colors [Array, NArray] the color at each point
-    # @param radii [Array, NArray] the desired tube radius at each point
-    # @param num_steps [Integer] the number of steps between each point, allowing for a more smooth tube
-    # @param num_segments [Integer] the number of segments each ring of the tube consists of, e.g. 3 would yield a triangular tube
+    #
+    # @param n            [Integer]       the number of points given
+    # @param points       [Array, NArray] the points the tube should go through
+    # @param colors       [Array, NArray] the color at each point
+    # @param radii        [Array, NArray] the desired tube radius at each point
+    # @param num_steps    [Integer]       the number of steps between each point,
+    #                                     allowing for a more smooth tube
+    # @param num_segments [Integer]       the number of segments each ring of the
+    #                                     tube consists of, e.g. 3 would yield a
+    #                                     triangular tube
+    #
     # @return [Integer]
     def createtubemesh(n, points, colors, radii, num_steps = 10, num_segments = 20)
       inquiry_uint do |mesh| # mesh should be Int?
@@ -547,12 +597,14 @@ module GR3
     # drawn and at which positions they should go through the data. If neither
     # x nor y nor z are set, 0.5 will be used for all three.
     # Returns meshes for the yz-slice, the xz-slice and the xy-slice.
-    # @param grid [NArray] 3D narray array containing the voxel data
-    # @param x [Numeric] the position of the slice through the xz-plane (0 to 1)
-    # @param y [Numeric] the position of the slice through the xz-plane (0 to 1)
-    # @param z [Numeric] the position of the slice through the xz-plane (0 to 1)
-    # @param step [Array] voxel sizes in each direction
-    # @param offset [Array] coordinate origin in each direction
+    #
+    # @param grid   [NArray]        3D narray array containing the voxel data
+    # @param x      [Numeric]       the position of the slice through the xz-plane (0 to 1)
+    # @param y      [Numeric]       the position of the slice through the xz-plane (0 to 1)
+    # @param z      [Numeric]       the position of the slice through the xz-plane (0 to 1)
+    # @param step   [Array, NArray] voxel sizes in each direction
+    # @param offset [Array, NArray] coordinate origin in each direction
+    #
     def createslicemeshes(grid, x = nil, y = nil, z = nil, step = nil, offset = nil)
       if [x, y, z].all?(&:nil?)
         x = 0.5
@@ -569,10 +621,11 @@ module GR3
     # using the current GR colormap. Use the x parameter to set the position of
     # the yz-slice.
     # Returns a mesh for the yz-slice.
-    # @param grid [NArray] 3D narray array containing the voxel data
-    # @param x [Numeric] the position of the slice through the xz-plane (0 to 1)
-    # @param step [Array] voxel sizes in each direction
-    # @param offset [Array] coordinate origin in each direction
+    #
+    # @param grid   [NArray]        3D narray array containing the voxel data
+    # @param x      [Numeric]       the position of the slice through the xz-plane (0 to 1)
+    # @param step   [Array, NArray] voxel sizes in each direction
+    # @param offset [Array, NArray] coordinate origin in each direction
     def createxslicemesh(grid, x = 0.5, step = nil, offset = nil)
       args = _preprocess_createslicemesh(grid, step, offset)
       grid = args.shift
@@ -586,10 +639,12 @@ module GR3
     # using the current GR colormap. Use the y parameter to set the position of
     # the xz-slice.
     # Returns a mesh for the xz-slice.
-    # @param grid [NArray] 3D narray array containing the voxel data
-    # @param y [Numeric] the position of the slice through the xz-plane (0 to 1)
-    # @param step [Array] voxel sizes in each direction
-    # @param offset [Array] coordinate origin in each direction
+    #
+    # @param grid   [NArray]        3D narray array containing the voxel data
+    # @param y      [Numeric]       the position of the slice through the xz-plane (0 to 1)
+    # @param step   [Array, NArray] voxel sizes in each direction
+    # @param offset [Array, NArray] coordinate origin in each direction
+    #
     def createyslicemesh(grid, y = 0.5, step = nil, offset = nil)
       args = _preprocess_createslicemesh(grid, step, offset)
       grid = args.shift
@@ -603,10 +658,12 @@ module GR3
     # using the current GR colormap. Use the z parameter to set the position of
     # the xy-slice.
     # Returns a mesh for the xy-slice.
-    # @param grid [NArray] 3D narray array containing the voxel data
-    # @param z [Numeric] the position of the slice through the xz-plane (0 to 1)
-    # @param step [Array] voxel sizes in each direction
-    # @param offset [Array] coordinate origin in each direction
+    #
+    # @param grid   [NArray]        3D narray array containing the voxel data
+    # @param z      [Numeric]       the position of the slice through the xz-plane (0 to 1)
+    # @param step   [Array, NArray] voxel sizes in each direction
+    # @param offset [Array, NArray] coordinate origin in each direction
+    #
     def createzslicemesh(grid, z = 0.5, step = nil, offset = nil)
       args = _preprocess_createslicemesh(grid, step, offset)
       grid = args.shift
@@ -617,15 +674,18 @@ module GR3
     end
 
     # Draw a yz-slice through the given data, using the current GR colormap.
-    # @param grid [NArray] 3D narray array containing the voxel data
-    # @param x [Numeric] the position of the slice through the yz-plane (0 to 1)
-    # @param step [Array] voxel sizes in each direction
-    # @param offset [Array] coordinate origin in each direction
-    # @param position [Array] the positions where the meshes should be drawn
-    # @param direction [Array] the forward directions the meshes should be facing at
-    # @param up [Array] the up directions
-    # @param color [Array] the colors the meshes should be drawn in, it will be multiplied with each vertex color
-    # @param scale [Array] the scaling factors
+    #
+    # @param grid      [NArray]        3D narray array containing the voxel data
+    # @param x         [Numeric]       the position of the slice through the yz-plane (0 to 1)
+    # @param step      [Array, NArray] voxel sizes in each direction
+    # @param offset    [Array, NArray] coordinate origin in each direction
+    # @param position  [Array, NArray] the positions where the meshes should be drawn
+    # @param direction [Array, NArray] the forward directions the meshes should be facing at
+    # @param up        [Array, NArray] the up directions
+    # @param color     [Array, NArray] the colors the meshes should be drawn in,
+    #                                  it will be multiplied with each vertex color
+    # @param scale     [Array, NArray] the scaling factors
+    #
     def drawxslicemesh(grid, x = 0.5, step = nil, offset = nil,
                        position = [0, 0, 0], direction = [0, 0, 1], up = [0, 1, 0],
                        color = [1, 1, 1], scale = [1, 1, 1])
@@ -635,15 +695,18 @@ module GR3
     end
 
     # Draw a xz-slice through the given data, using the current GR colormap.
-    # @param grid [NArray] 3D narray array containing the voxel data
-    # @param y [Numeric] the position of the slice through the xz-plane (0 to 1)
-    # @param step [Array] voxel sizes in each direction
-    # @param offset [Array] coordinate origin in each direction
-    # @param position [Array] the positions where the meshes should be drawn
-    # @param direction [Array] the forward directions the meshes should be facing at
-    # @param up [Array] the up directions
-    # @param color [Array] the colors the meshes should be drawn in, it will be multiplied with each vertex color
-    # @param scale [Array] the scaling factors
+    #
+    # @param grid      [NArray]        3D narray array containing the voxel data
+    # @param y         [Numeric]       the position of the slice through the xz-plane (0 to 1)
+    # @param step      [Array, NArray] voxel sizes in each direction
+    # @param offset    [Array, NArray] coordinate origin in each direction
+    # @param position  [Array, NArray] the positions where the meshes should be drawn
+    # @param direction [Array, NArray] the forward directions the meshes should be facing at
+    # @param up        [Array, NArray] the up directions
+    # @param color     [Array, NArray] the colors the meshes should be drawn in,
+    #                                  it will be multiplied with each vertex color
+    # @param scale     [Array, NArray] the scaling factors
+    #
     def drawyslicemesh(grid, y = 0.5, step = nil, offset = nil,
                        position = [0, 0, 0], direction = [0, 0, 1], up = [0, 1, 0],
                        color = [1, 1, 1], scale = [1, 1, 1])
@@ -653,15 +716,18 @@ module GR3
     end
 
     # Draw a xy-slice through the given data, using the current GR colormap.
-    # @param grid [NArray] 3D narray array containing the voxel data
-    # @param z [Numeric] the position of the slice through the xy-plane (0 to 1)
-    # @param step [Array] voxel sizes in each direction
-    # @param offset [Array] coordinate origin in each direction
-    # @param position [Array] the positions where the meshes should be drawn
-    # @param direction [Array] the forward directions the meshes should be facing at
-    # @param up [Array] the up directions
-    # @param color [Array] the colors the meshes should be drawn in, it will be multiplied with each vertex color
-    # @param scale [Array] the scaling factors
+    #
+    # @param grid      [NArray]        3D narray array containing the voxel data
+    # @param z         [Numeric]       the position of the slice through the xy-plane (0 to 1)
+    # @param step      [Array, NArray] voxel sizes in each direction
+    # @param offset    [Array, NArray] coordinate origin in each direction
+    # @param position  [Array, NArray] the positions where the meshes should be drawn
+    # @param direction [Array, NArray] the forward directions the meshes should be facing at
+    # @param up        [Array, NArray] the up directions
+    # @param color     [Array, NArray] the colors the meshes should be drawn in,
+    #                                  it will be multiplied with each vertex color
+    # @param scale     [Array, NArray] the scaling factors
+    #
     def drawzslicemesh(grid, z = 0.5, step = nil, offset = nil,
                        position = [0, 0, 0], direction = [0, 0, 1], up = [0, 1, 0],
                        color = [1, 1, 1], scale = [1, 1, 1])
@@ -674,17 +740,20 @@ module GR3
     # Use the parameters x, y or z to specify what slices should be drawn and at
     # which positions they should go through the data. If neither x nor y nor
     # z are set, 0.5 will be used for all three.
+    #
     # @param grid [NArray] 3D narray array containing the voxel data
-    # @param x [Numeric] the position of the slice through the yz-plane (0 to 1)
-    # @param y [Numeric] the position of the slice through the xz-plane (0 to 1)
-    # @param z [Numeric] the position of the slice through the xy-plane (0 to 1)
-    # @param step [Array] voxel sizes in each direction
-    # @param offset [Array] coordinate origin in each direction
-    # @param position [Array] the positions where the meshes should be drawn
-    # @param direction [Array] the forward directions the meshes should be facing at
-    # @param up [Array] the up directions
-    # @param color [Array] the colors the meshes should be drawn in, it will be multiplied with each vertex color
-    # @param scale [Array] the scaling factors
+    # @param x         [Numeric]       the position of the slice through the yz-plane (0 to 1)
+    # @param y         [Numeric]       the position of the slice through the xz-plane (0 to 1)
+    # @param z         [Numeric]       the position of the slice through the xy-plane (0 to 1)
+    # @param step      [Array, NArray] voxel sizes in each direction
+    # @param offset    [Array, NArray] coordinate origin in each direction
+    # @param position  [Array, NArray] the positions where the meshes should be drawn
+    # @param direction [Array, NArray] the forward directions the meshes should be facing at
+    # @param up        [Array, NArray] the up directions
+    # @param color     [Array, NArray] the colors the meshes should be drawn in,
+    #                                  it will be multiplied with each vertex color
+    # @param scale     [Array, NArray] the scaling factors
+    #
     def drawslicemeshes(grid, x = nil, y = nil, z = nil, step = nil,
                         offset = nil, position = [0, 0, 0], direction = [0, 0, 1], up = [0, 1, 0],
                         color = [1, 1, 1], scale = [1, 1, 1])
@@ -757,6 +826,7 @@ module GR3
   IA_END_OF_LIST        = 0
   IA_FRAMEBUFFER_WIDTH  = 1
   IA_FRAMEBUFFER_HEIGHT = 2
+  IA_NUM_THREADS        = 3
 
   # Error
   ERROR_NONE                   =  0
@@ -787,6 +857,11 @@ module GR3
   DRAWABLE_OPENGL = 1
   DRAWABLE_GKS    = 2
 
+  # Projection
+  PROJECTION_PERSPECTIVE  = 0
+  PROJECTION_PARALLEL     = 1
+  PROJECTION_ORTHOGRAPHIC = 2
+
   # SurfaceOption
   SURFACE_DEFAULT     =  0
   SURFACE_NORMALS     =  1