ruby-gr 0.0.20 → 0.0.25

data/lib/gr/ffi.rb

@@ -15,7 +15,7 @@ module GR
       raise LoadError, 'Could not find GR Framework'
     end
 
-    extend GRCommons::Extern
+    extend GRCommons::TryExtern
 
     # https://github.com/sciapp/gr/blob/master/lib/gr/gr.h
     # keep same order
@@ -41,6 +41,8 @@ module GR
                'int, int, int, int, int, int, int *)'
     try_extern 'void gr_polarcellarray(double, double, double, double, double, double, ' \
                'int, int, int, int, int, int, int *)'
+    try_extern 'void gr_nonuniformpolarcellarray(double, double, double *, double *, ' \
+               'int, int, int, int, int, int, int *);'
     try_extern 'void gr_gdp(int, double *, double *, int, int, int *)'
     try_extern 'void gr_spline(int, double *, double *, int, int)'
     try_extern 'void gr_gridit(int, double *, double *, double *, int, int, ' \
@@ -174,7 +176,7 @@ module GR
     try_extern 'void gr_shadepoints(int, double *, double *, int, int, int)'
     try_extern 'void gr_shadelines(int, double *, double *, int, int, int)'
     try_extern 'void gr_panzoom(double, double, double, double, double *, double *, double *, double *)'
-    # try_extern 'int gr_findboundary(int, double *, double *, double, double (*)(double, double), int, int *)'
+    try_extern 'int gr_findboundary(int, double *, double *, double, double (*)(double, double), int, int *)'
     try_extern 'void gr_setresamplemethod(unsigned int flag)'
     try_extern 'void gr_inqresamplemethod(unsigned int *flag)'
     try_extern 'void gr_path(int, double *, double *, const char *)'
@@ -202,5 +204,6 @@ module GR
     try_extern 'void gr_inqtext3d(double, double, double, char *, int axis, double *, double *)'
     try_extern 'void gr_settextencoding(int)'
     try_extern 'void gr_inqtextencoding(int *)'
+    # gr_setcallback(char *(*)(const char *));
   end
 end

data/lib/gr/plot.rb

@@ -38,12 +38,49 @@ module GR
 
     # Keyword options conform to GR.jl.
     KW_ARGS = %i[accelerate algorithm alpha ax backgroundcolor barwidth baseline
-                 clabels clear clim color colormap crange figsize grid horizontal
-                 isovalue kind label labels levels location nbins ratio rotation
-                 scale size spec subplot tilt title update xaxis xflip xform
-                 xlabel xlim xlog xrange xticks yaxis yflip ylabel ylim ylog
-                 zflip yrange yticks viewport vp where window zaxis zlabel zlim
-                 zlog zrange zticks].freeze
+                 clabels clear clim color colormap crange figsize font grid
+                 horizontal isovalue kind label labels levels location nbins
+                 ratio rotation scale size spec subplot tilt title update xaxis
+                 xflip xform xlabel xlim xlog xrange xticks yaxis yflip ylabel
+                 ylim ylog zflip yrange yticks viewport vp where window zaxis
+                 zlabel zlim zlog zrange zticks].freeze
+
+    FONTS = {
+      times_roman: 101,
+      times_italic: 102,
+      times_bold: 103,
+      times_bolditalic: 104,
+      helvetica_regular: 105,
+      helvetica_oblique: 106,
+      helvetica_bold: 107,
+      helvetica_boldoblique: 108,
+      courier_regular: 109,
+      courier_oblique: 110,
+      courier_bold: 111,
+      courier_boldoblique: 112,
+      symbol: 113,
+      bookman_light: 114,
+      bookman_lightitalic: 115,
+      bookman_demi: 116,
+      bookman_demiitalic: 117,
+      newcenturyschlbk_roman: 118,
+      newcenturyschlbk_italic: 119,
+      newcenturyschlbk_bold: 120,
+      newcenturyschlbk_bolditalic: 121,
+      avantgarde_book: 122,
+      avantgarde_bookoblique: 123,
+      avantgarde_demi: 124,
+      avantgarde_demioblique: 125,
+      palatino_roman: 126,
+      palatino_italic: 127,
+      palatino_bold: 128,
+      palatino_bolditalic: 129,
+      zapfchancery_mediumitalic: 130,
+      zapfdingbats: 131,
+      cmuserif_math: 232, # original: cmuserif-math
+      dejavusans: 233,
+      pingfangsc: 234
+    }.freeze
 
     @last_plot = nil
     class << self
@@ -62,7 +99,7 @@ module GR
       # label(singular form) is a original keyword arg which GR.jl does not have.
       kvs[:labels] ||= [kvs[:label]] if kvs.has_key? :label
 
-      # Don't use || because we need to tell `false` from `nil`
+      # Don't use ||= here, because we need to tell `false` from `nil`
       kvs[:size]    = [600, 450]   unless kvs.has_key? :size
       kvs[:ax]      = false        unless kvs.has_key? :ax
       kvs[:subplot] = [0, 1, 0, 1] unless kvs.has_key? :subplot
@@ -185,8 +222,12 @@ module GR
         minmax
       end
 
-      major_count = %i[wireframe surface plot3 scatter3 polar polarhist
-                       polarheatmap trisurf volume].include?(kind) ? 2 : 5
+      major_count = if %i[wireframe surface plot3 scatter3 polar polarhist
+                          polarheatmap trisurf volume].include?(kind)
+                      2
+                    else
+                      5
+                    end
 
       kvs[:xticks] = [kvs[:xticks], major_count] if kvs[:xticks].is_a? Numeric
       kvs[:yticks] = [kvs[:yticks], major_count] if kvs[:yticks].is_a? Numeric
@@ -198,10 +239,10 @@ module GR
         xmax += 0.5
       end
       xtick, majorx = if (scale & GR::OPTION_X_LOG) == 0
-                        unless %i[heatmap polarheatmap].include?(kind)
-                          unless kvs.has_key?(:xlim)
-                            xmin, xmax = GR.adjustlimits(xmin, xmax) unless kvs[:panzoom]
-                          end
+                        if !%i[heatmap polarheatmap].include?(kind) &&
+                           !kvs.has_key?(:xlim) &&
+                           !kvs[:panzoom]
+                          xmin, xmax = GR.adjustlimits(xmin, xmax)
                         end
                         if kvs.has_key?(:xticks)
                           kvs[:xticks]
@@ -227,10 +268,10 @@ module GR
         end
       end
       ytick, majory = if (scale & GR::OPTION_Y_LOG) == 0
-                        unless %i[heatmap polarheatmap].include?(kind)
-                          unless kvs.has_key?(:ylim)
-                            ymin, ymax = GR.adjustlimits(ymin, ymax) unless kvs[:panzoom]
-                          end
+                        if !%i[heatmap polarheatmap].include?(kind) &&
+                           !kvs.has_key?(:ylim) &&
+                           !kvs[:panzoom]
+                          ymin, ymax = GR.adjustlimits(ymin, ymax)
                         end
                         if kvs.has_key?(:yticks)
                           kvs[:yticks]
@@ -341,29 +382,29 @@ module GR
         GR.axes(xtick, ytick, xorg[1], yorg[1], -majorx, -majory, -ticksize)
       end
 
-      if kvs[:title]
+      if kvs.has_key?(:title)
         GR.savestate
         GR.settextalign(GR::TEXT_HALIGN_CENTER, GR::TEXT_VALIGN_TOP)
-        text(0.5 * (viewport[0] + viewport[1]), vp[3], kvs[:title])
+        text(0.5 * (viewport[0] + viewport[1]), vp[3], kvs[:title].to_s)
         GR.restorestate
       end
       if %i[wireframe surface plot3 scatter3 trisurf volume].include?(kind)
-        xlabel = kvs[:xlabel] || ''
-        ylabel = kvs[:ylabel] || ''
-        zlabel = kvs[:zlabel] || ''
+        xlabel = (kvs[:xlabel] || '').to_s
+        ylabel = (kvs[:ylabel] || '').to_s
+        zlabel = (kvs[:zlabel] || '').to_s
         GR.titles3d(xlabel, ylabel, zlabel)
       else
         if kvs.has_key?(:xlabel)
           GR.savestate
           GR.settextalign(GR::TEXT_HALIGN_CENTER, GR::TEXT_VALIGN_BOTTOM)
-          text(0.5 * (viewport[0] + viewport[1]), vp[2] + 0.5 * charheight, kvs[:xlabel])
+          text(0.5 * (viewport[0] + viewport[1]), vp[2] + 0.5 * charheight, kvs[:xlabel].to_s)
           GR.restorestate
         end
         if kvs.has_key?(:ylabel)
           GR.savestate
           GR.settextalign(GR::TEXT_HALIGN_CENTER, GR::TEXT_VALIGN_TOP)
           GR.setcharup(-1, 0)
-          text(vp[0] + 0.5 * charheight, 0.5 * (viewport[2] + viewport[3]), kvs[:ylabel])
+          text(vp[0] + 0.5 * charheight, 0.5 * (viewport[2] + viewport[3]), kvs[:ylabel].to_s)
           GR.restorestate
         end
       end
@@ -471,7 +512,7 @@ module GR
       if kvs.has_key?(:title)
         GR.savestate
         GR.settextalign(GR::TEXT_HALIGN_CENTER, GR::TEXT_VALIGN_TOP)
-        text(0.5 * (viewport[0] + viewport[1]), vp[3], kvs[:title])
+        text(0.5 * (viewport[0] + viewport[1]), vp[3], kvs[:title].to_s)
         GR.restorestate
       end
       GR.selntran(1)
@@ -573,7 +614,22 @@ module GR
         # Not yet.
       end
 
-      GR.settextfontprec(232, 3)
+      if kvs.has_key?(:font)
+        name = kvs[:font]
+        # 'Cmuserif-Math' => :cmuserif_math
+        sym_name = name.to_s.gsub('-', '_').downcase.to_sym
+        if FONTS.include?(sym_name)
+          font = FONTS[sym_name]
+          GR.settextfontprec(font, font > 200 ? 3 : 0)
+        else
+          warn "Unknown font name: #{name}" # should raise error?
+        end
+      else
+        # The following fonts are the default in GR.jl
+        # Japanese, Chinese, Korean, etc. cannot be displayed.
+
+        # GR.settextfontprec(232, 3) # CM Serif Roman
+      end
 
       set_viewport(kind, kvs[:subplot])
       unless kvs[:ax]
@@ -641,8 +697,7 @@ module GR
           if z || c
             if c
               cmin, cmax = kvs[:crange]
-              c = c.to_a if narray?(c)
-              c.map! { |i| normalize_color(i, cmin, cmax) }
+              c = c.map { |i| normalize_color(i, cmin, cmax) }
               cind = c.map { |i| (1000 + i * 255).round }
             end
             x.length.times do |i|
@@ -743,9 +798,10 @@ module GR
           else
             h = levels
           end
-          if kind == :contour
+          case kind
+          when :contour
             GR._contour_(x, y, h, z, clabels ? 1 : 1000)
-          elsif kind == :contourf
+          when :contourf
             GR._contourf_(x, y, h, z, clabels ? 1 : 0)
           end
           colorbar(0, h.length)
@@ -834,7 +890,7 @@ module GR
           GR.setmarkertype(GR::MARKERTYPE_SOLID_CIRCLE)
           if c
             cmin, cmax = kvs[:crange]
-            c = c.map { |i| normalize_color(i, cmin, cmax) } # NArray -> Array
+            c = c.map { |i| normalize_color(i, cmin, cmax) }
             cind = c.map { |i| (1000 + i * 255).round }
             x.length.times do |i|
               GR.setmarkercolorind(cind[i])
@@ -1040,13 +1096,16 @@ module GR
 
     # Normalize a color c with the range [cmin, cmax]
     #   0 <= normalize_color(c, cmin, cmax) <= 1
+    # Note: narray.map{|i| normalize_color(i)} There's room for speedup.
     def normalize_color(c, cmin, cmax)
+      c = c.to_f # if c is Integer
       c = c.clamp(cmin, cmax) - cmin
       c /= (cmax - cmin) if cmin != cmax
       c
     end
 
     def inqtext(x, y, s)
+      s = s.to_s
       if s.length >= 2 && s[0] == '$' && s[-1] == '$'
         GR.inqmathtex(x, y, s[1..-2])
       elsif s.include?('\\') || s.include?('_') || s.include?('^')
@@ -1057,6 +1116,7 @@ module GR
     end
 
     def text(x, y, s)
+      s = s.to_s
       if s.length >= 2 && s[0] == '$' && s[-1] == '$'
         GR.mathtex(x, y, s[1..-2])
       elsif s.include?('\\') || s.include?('_') || s.include?('^')
@@ -1156,20 +1216,12 @@ module GR
       [w, h]
     end
 
-    # NOTE: duplicated definition (GRCommonUtils)
     def equal_length(*args)
-      lengths = args.map(&:length)
-      unless lengths.all? { |l| l == lengths[0] }
-        raise ArgumentError,
-              'Sequences must have same length.'
-      end
-
-      lengths[0]
+      GRCommons::GRCommonUtils.equal_length(*args)
     end
 
-    # NOTE: duplicated definition (GRCommonUtils)
     def narray?(data)
-      defined?(Numo::NArray) && data.is_a?(Numo::NArray)
+      GRCommons::GRCommonUtils.narray?(data)
     end
   end
 

data/lib/gr3.rb

@@ -40,47 +40,52 @@
 #
 # 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'
+
   # Platforms |  path
   # Windows   |  bin/libGR3.dll
-  # MacOSX    |  lib/libGR3.so (NOT .dylib)
+  # MacOSX    |  lib/libGR3.dylib (v0.53.0 .so)
   # Ubuntu    |  lib/libGR3.so
-  if Object.const_defined?(:RubyInstaller)
-    ENV['GRDIR'] ||= [
-      RubyInstaller::Runtime.msys2_installation.msys_path,
-      RubyInstaller::Runtime.msys2_installation.mingwarch
-    ].join(File::ALT_SEPARATOR)
-    self.ffi_lib = File.expand_path('bin/libGR3.dll', ENV['GRDIR'])
-    RubyInstaller::Runtime.add_dll_directory(File.dirname(ffi_lib))
-  else
-    raise Error, 'Please set env variable GRDIR' unless ENV['GRDIR']
-
-    self.ffi_lib = File.expand_path('lib/libGR3.so', ENV['GRDIR'])
-  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
+  lib_path = GRCommons::GRLib.search(lib_names, pkg_name)
 
-  # change the default encoding to UTF-8.
-  ENV['GKS_ENCODING'] ||= 'utf8'
+  raise NotFoundError, "#{lib_names} not found" if lib_path.nil?
+
+  self.ffi_lib = lib_path
 
-  require_relative 'gr_commons/gr_commons'
   require_relative 'gr3/version'
   require_relative 'gr3/ffi'
   require_relative 'gr3/gr3base'
@@ -124,70 +129,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)
@@ -198,31 +215,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)
@@ -230,6 +247,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|
@@ -240,150 +258,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
@@ -395,10 +422,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
@@ -413,6 +441,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|
@@ -426,29 +455,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
@@ -456,17 +488,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
@@ -474,12 +509,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?
@@ -554,12 +594,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
@@ -576,10 +618,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
@@ -593,10 +636,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
@@ -610,10 +655,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
@@ -624,15 +671,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])
@@ -642,15 +692,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])
@@ -660,15 +713,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])
@@ -681,17 +737,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])