Class: FMOD::Geometry

Inherits:
Handle
  • Object
show all
Includes:
Enumerable
Defined in:
lib/fmod/geometry.rb

Overview

FMOD supports the supply of polygon mesh data, that can be processed in realtime to create the effect of occlusion in a real 3D world. In real world terms, the user can stop sounds travelling through walls, or even confine reverb inside a geometric volume so that it doesn’t leak out into other areas.

Defined Under Namespace

Classes: Polygon, Rotation

Instance Attribute Summary collapse

Attributes inherited from Handle

#user_data

Instance Method Summary collapse

Methods inherited from Handle

#initialize, #int_ptr, #release, #to_s

Constructor Details

This class inherits a constructor from FMOD::Handle

Instance Attribute Details

#active ⇒ Boolean

Value indicating if object will be processed in the geometry engine.

Returns:

  • (Boolean) 


19
 
# File 'lib/fmod/geometry.rb', line 19

bool_reader(:active, :Geometry_GetActive)

#polygon_count ⇒ Integer Also known as: size

Retrieves the number of polygons stored within this FMOD::Geometry object.

Returns:

  • (Integer) 


27
 
# File 'lib/fmod/geometry.rb', line 27

integer_reader(:polygon_count, :Geometry_GetNumPolygons)

#position ⇒ Vector

The position of the object in world space, which is the same space FMOD sounds and listeners reside in.

Returns:



38
39
40
41
 
# File 'lib/fmod/geometry.rb', line 38

def position
  FMOD.invoke(:Geometry_GetPosition, self, vector = Vector.zero)
  vector
end

#rotation ⇒ Rotation

The current orientation of the geometry object.

Returns:

See Also:



74
75
76
77
78
 
# File 'lib/fmod/geometry.rb', line 74

def rotation
  forward, up = Vector.zero, Vector.zero
  FMOD.invoke(:Geometry_GetRotation, self, forward, up)
  Rotation.new(forward, up)
end

#scale ⇒ Vector

The relative scale vector of the geometry object. An object can be scaled/warped in all 3 dimensions separately using the vector without having to modify polygon data.

Returns:



57
58
59
60
 
# File 'lib/fmod/geometry.rb', line 57

def scale
  FMOD.invoke(:Geometry_GetScale, self, vector = Vector.zero)
  vector
end

Instance Method Details

#[](index) ⇒ Polygon

Retrieves the Polygon at the specified index.

Parameters:

  • index (Integer) —

    The index of the Polygon to retrieve.

Returns:



128
129
130
131
 
# File 'lib/fmod/geometry.rb', line 128

def [](index)
  return nil unless index.between?(0, polygon_count)
  Polygon.send(:new, self, index)
end

#add_polygon(vertices, direct = 0.0, reverb = 0.0, double_sided = false) ⇒ Object

Note:

A minimum of 3 vertices is required to create a Polygon.

Adds a polygon to an geometry object.

Parameters:

  • vertices (Array<Vector>) —

    array of vertices located in object space.

  • direct (Float) (defaults to: 0.0) —

    Occlusion value which affects volume or audible frequencies.

    • Minimum: 0.0 The polygon does not occlude volume or audible frequencies (sound will be fully audible)

    • Maximum: 1.0 The polygon fully occludes (sound will be silent)

  • reverb (Float) (defaults to: 0.0) —

    Occlusion value from 0.0 to 1.0 which affects the reverb mix.

    • Minimum: 0.0 The polygon does not occlude reverb (reverb reflections still travel through this polygon)

    • Maximum: 1.0 The polygon fully occludes reverb (reverb reflections will be silent through this polygon).

  • double_sided (Boolean) (defaults to: false) —

    Description of polygon if it is double sided or single sided.

    • true: Polygon is double sided

    • false: Polygon is single sided, and the winding of the polygon (which determines the polygon’s normal) determines which side of the polygon will cause occlusion.



156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/fmod/geometry.rb', line 156

def add_polygon(vertices, direct = 0.0, reverb = 0.0, double_sided = false)
  size = vertices.size
  unless size >= 3
    message = "3 or more vertices required for polygon: #{size} specified"
    raise ArgumentError, message
  end
  vectors = vertices.map(&:to_str).join
  direct = direct.clamp(0.0, 1.0)
  reverb = reverb.clamp(0.0, 1.0)
  FMOD.invoke(:Geometry_AddPolygon, self, direct, reverb,
              double_sided.to_i, size, vectors, index = "\0" * SIZEOF_INT)
  Polygon.send(:new, self, index.unpack1('l'))
end

#each {|polygon| ... } ⇒ self #each ⇒ Enumerator

Enumerates the polygons contained within the FMOD::Geometry.

Overloads:

  • #each {|polygon| ... } ⇒ self

    When called with block, yields each Polygon within the object before returning self.

    Yields:

    • (polygon) —

      Yields a polygon to the block.

    Yield Parameters:

    • polygon (Polygon) —

      The current enumerated polygon.

    Returns:

    • (self)
  • #each ⇒ Enumerator

    When no block specified, returns an Enumerator for the FMOD::Geometry.

    Returns:

    • (Enumerator) 


205
206
207
208
209
 
# File 'lib/fmod/geometry.rb', line 205

def each
  return to_enum(:each) unless block_given?
  (0...polygon_count).each { |i| yield self[i] }
  self
end

#max_polygons ⇒ Integer

Retrieves the maximum number of polygons allocatable for this object.

This is not the number of polygons currently present.

Returns:

  • (Integer) 


107
108
109
110
111
 
# File 'lib/fmod/geometry.rb', line 107

def max_polygons
  max = "\0" * SIZEOF_INT
  FMOD.invoke(:Geometry_GetMaxPolygons, self, max, nil)
  max.unpack1('l')
end

#max_vertices ⇒ Integer

Retrieves the maximum number of vertices allocatable for this object.

This is not the number of vertices currently present.

Returns:

  • (Integer) 


118
119
120
121
122
 
# File 'lib/fmod/geometry.rb', line 118

def max_vertices
  max = "\0" * SIZEOF_INT
  FMOD.invoke(:Geometry_GetMaxPolygons, self, nil, max)
  max.unpack1('l')
end

#polygons ⇒ Array<Polygon>

Retrieves an array of Polygon objects within this FMOD::Geometry.

Returns:



214
215
216
 
# File 'lib/fmod/geometry.rb', line 214

def polygons
  (0...polygon_count).map { |i| self[i] }
end

#rotate(forward, upward) ⇒ Object

Sets the orientation of the geometry object.

Parameters:

  • forward (Vector) —

    The forwards orientation of the geometry object. This vector must be of unit length and perpendicular to the upward vector. You can specify nil to not update the forwards orientation of the geometry object.

  • upward (Vector) —

    The upwards orientation of the geometry object. This vector must be of unit length and perpendicular to the forward vector. You can specify nil to not update the upwards orientation of the geometry object.



95
96
97
98
99
 
# File 'lib/fmod/geometry.rb', line 95

def rotate(forward, upward)
  FMOD.type?(forward, Vector) unless forward.nil?
  FMOD.type?(upward, Vector) unless upward.nil?
  FMOD.invoke(:Geometry_SetRotation, self, forward, upward)
end

#save(filename) ⇒ Boolean #save ⇒ String

Serializes the FMOD::Geometry object into a binary block.

Overloads:

  • #save(filename) ⇒ Boolean

    Returns true if object was successfully flushed to disk, otherwise false.

    Parameters:

    • filename (String) —

      A filename where object will be saved to.

    Returns:

    • (Boolean) —

      true if object was successfully flushed to disk, otherwise false.

  • #save ⇒ String

    Serializes the FMOD::Geometry object and returns the data as a binary string.

    Returns:

See Also:



182
183
184
185
186
187
188
189
190
191
 
# File 'lib/fmod/geometry.rb', line 182

def save(filename = nil)
  FMOD.invoke(:Geometry_Save, self, nil, size = "\0" * SIZEOF_INT)
  data = "\0" * size.unpack1('l')
  FMOD.invoke(:Geometry_Save, self, data, size)
  unless filename.nil?
    File.open(filename, 'wb') { |file| file.write(data) } rescue return false
    return true
  end
  data
end