7. Core API Reference | Geometry

An interface that allows the setup and modification of geometry for occlusion

Polygons:

• Geometry::setPolygonAttributes Sets individual attributes for a polygon inside a geometry object.
• Geometry::getPolygonAttributes Retrieves the attributes for a polygon.
• Geometry::getPolygonNumVertices Gets the number of vertices in a polygon.
• Geometry::setPolygonVertex Alters the position of a polygon's vertex inside a geometry object.
• Geometry::getPolygonVertex Retrieves the position of a vertex.

Object Spatialization:

• Geometry::setPosition Sets the 3D position of the object.
• Geometry::getPosition Retrieves the 3D position of the object.
• Geometry::setRotation Sets the 3D orientation of the object.
• Geometry::getRotation Retrieves the 3D orientation of the object.
• Geometry::setScale Sets the 3D scale of the object.
• Geometry::getScale Retrieves the 3D scale of the object.

Object General:

• Geometry::addPolygon Adds a polygon.
• Geometry::setActive Sets whether an object is processed by the geometry engine.
• Geometry::getActive Retrieves whether an object is processed by the geometry engine.
• Geometry::getMaxPolygons Retrieves the maximum number of polygons and vertices allocatable for this object.
• Geometry::getNumPolygons Retrieves the number of polygons in this object.
• Geometry::setUserData Sets a user value associated with this object.
• Geometry::getUserData Retrieves a user value associated with this object.
• Geometry::release Frees a geometry object and releases its memory.
• Geometry::save Saves the geometry object as a serialized binary block to a user memory buffer.

Geometry::addPolygon

Adds a polygon.

FMOD_RESULT Geometry::addPolygon(
  float directocclusion,
  float reverbocclusion,
  bool doublesided,
  int numvertices,
  const FMOD_VECTOR *vertices,
  int *polygonindex
);

FMOD_RESULT FMOD_Geometry_AddPolygon(
  FMOD_GEOMETRY *geometry,
  float directocclusion,
  float reverbocclusion,
  FMOD_BOOL doublesided,
  int numvertices,
  const FMOD_VECTOR *vertices,
  int *polygonindex
);

RESULT Geometry.addPolygon(
  float directocclusion,
  float reverbocclusion,
  bool doublesided,
  int numvertices,
  VECTOR[] vertices,
  out int polygonindex
);

directocclusion

Occlusion factor of the polygon for the direct path where 0 represents no occlusion and 1 represents full occlusion.

• Range: [0, 1]
• Default: 0

reverbocclusion

Occlusion factor of the polygon for the reverb path where 0 represents no occlusion and 1 represents full occlusion.

• Range: [0, 1]
• Default: 0

doublesided

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.

• Units: Boolean

numvertices

Number of vertices in this polygon. This must be at least 3.

vertices

Array of vertices located in object space of length numvertices. (FMOD_VECTOR)

polygonindex OutOpt

Polygon index. Use this with other per polygon based functions as a handle.

All vertices must lay in the same plane otherwise behavior may be unpredictable. The polygon is assumed to be convex. A non convex polygon will produce unpredictable behavior. Polygons with zero area will be ignored.

Polygons cannot be added if already at the maximum number of polygons or if the addition of their verticies would result in exceeding the maximum number of vertices.

Vertices of an object are in object space, not world space, and so are relative to the position, or center of the object. See Geometry::setPosition.

See Also: Geometry::setPolygonAttributes, Geometry::getNumPolygons, Geometry::getMaxPolygons

Geometry::getActive

Retrieves whether an object is processed by the geometry engine.

FMOD_RESULT Geometry::getActive(
  bool *active
);

FMOD_RESULT FMOD_Geometry_GetActive(
  FMOD_GEOMETRY *geometry,
  FMOD_BOOL *active
);

RESULT Geometry.getActive(
  out bool active
);

Geometry.getActive(
  active
);

active Out

Object is allowed to be processed by the geometry engine.

• Units: Boolean
• Default: True

See Also: Geometry::setActive

Geometry::getMaxPolygons

Retrieves the maximum number of polygons and vertices allocatable for this object.

FMOD_RESULT Geometry::getMaxPolygons(
  int *maxpolygons,
  int *maxvertices
);

FMOD_RESULT FMOD_Geometry_GetMaxPolygons(
  FMOD_GEOMETRY *geometry,
  int *maxpolygons,
  int *maxvertices
);

RESULT Geometry.getMaxPolygons(
  out int maxpolygons,
  out int maxvertices
);

Geometry.getMaxPolygons(
  maxpolygons,
  maxvertices
);

maxpolygons OutOpt

Maximum possible number of polygons in this object.

maxvertices OutOpt

Maximum possible number of vertices in this object.

The maximum number was set with System::createGeometry.

See Also: System::loadGeometry

Geometry::getNumPolygons

Retrieves the number of polygons in this object.

FMOD_RESULT Geometry::getNumPolygons(
  int *numpolygons
);

FMOD_RESULT FMOD_Geometry_GetNumPolygons(
  FMOD_GEOMETRY *geometry,
  int *numpolygons
);

RESULT Geometry.getNumPolygons(
  out int numpolygons
);

Geometry.getNumPolygons(
  numpolygons
);

numpolygons Out

Number of polygons.

See Also: Geometry::AddPolygon

Geometry::getPolygonAttributes

Retrieves the attributes for a polygon.

FMOD_RESULT Geometry::getPolygonAttributes(
  int index,
  float *directocclusion,
  float *reverbocclusion,
  bool *doublesided
);

FMOD_RESULT FMOD_Geometry_GetPolygonAttributes(
  FMOD_GEOMETRY *geometry,
  int index,
  float *directocclusion,
  float *reverbocclusion,
  FMOD_BOOL *doublesided
);

RESULT Geometry.getPolygonAttributes(
  int index,
  out float directocclusion,
  out float reverbocclusion,
  out bool doublesided
);

Geometry.getPolygonAttributes(
  index,
  directocclusion,
  reverbocclusion,
  doublesided
);

index

Polygon index.

• Range: [0, Geometry::getNumPolygons)

directocclusion OutOpt

Occlusion factor for the direct path where 0 represents no occlusion and 1 represents full occlusion.

• Range: [0, 1]
• Default: 0
• Units: Linear

reverbocclusion OutOpt

Occlusion factor for the reverb path where 0 represents no occlusion and 1 represents full occlusion.

• Range: [0, 1]
• Default: 0
• Units: Linear

doublesided OutOpt

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.

• Units: Boolean

See Also: Geometry::setPolygonAttributes

Geometry::getPolygonNumVertices

Gets the number of vertices in a polygon.

FMOD_RESULT Geometry::getPolygonNumVertices(
  int index,
  int *numvertices
);

FMOD_RESULT FMOD_Geometry_GetPolygonNumVertices(
  FMOD_GEOMETRY *geometry,
  int index,
  int *numvertices
);

RESULT Geometry.getPolygonNumVertices(
  int index,
  out int numvertices
);

Geometry.getPolygonNumVertices(
  index,
  numvertices
);

index

Polygon index.

• Range: [0, Geometry::getNumPolygons)

numvertices OutOpt

Number of vertices.

Geometry::getPolygonVertex

Retrieves the position of a vertex.

FMOD_RESULT Geometry::getPolygonVertex(
  int index,
  int vertexindex,
  FMOD_VECTOR *vertex
);

FMOD_RESULT FMOD_Geometry_GetPolygonVertex(
  FMOD_GEOMETRY *geometry,
  int index,
  int vertexindex,
  FMOD_VECTOR *vertex
);

RESULT Geometry.getPolygonVertex(
  int index,
  int vertexindex,
  out VECTOR vertex
);

Geometry.getPolygonVertex(
  index,
  vertexindex,
  vertex
);

index

Polygon index.

• Range: [0, Geometry::getNumPolygons)

vertexindex

Polygon vertex index.

• Range: [0, Geometry::getPolygonNumVertices (index) )

vertex Out

3D Position of the vertex. (FMOD_VECTOR)

• Units: Distance units

Vertices are relative to the position of the object. See Geometry::setPosition.

See Also: Geometry::setPolygonVertex

Geometry::getPosition

Retrieves the 3D position of the object.

FMOD_RESULT Geometry::getPosition(
  FMOD_VECTOR *position
);

FMOD_RESULT FMOD_Geometry_GetPosition(
  FMOD_GEOMETRY *geometry,
  FMOD_VECTOR *position
);

RESULT Geometry.getPosition(
  out VECTOR position
);

Geometry.getPosition(
  position
);

position Out

3D position. (FMOD_VECTOR)

• Units: Distance units
• Default: (0, 0, 0)

Position is in world space.

See Also: Geometry::setPosition

Geometry::getRotation

Retrieves the 3D orientation of the object.

FMOD_RESULT Geometry::getRotation(
  FMOD_VECTOR *forward,
  FMOD_VECTOR *up
);

FMOD_RESULT FMOD_Geometry_GetRotation(
  FMOD_GEOMETRY *geometry,
  FMOD_VECTOR *forward,
  FMOD_VECTOR *up
);

RESULT Geometry.getRotation(
  out VECTOR forward,
  out VECTOR up
);

Geometry.getRotation(
  forward,
  up
);

forward OutOpt

Forwards orientation. This vector must be of unit length and perpendicular to the up vector. (FMOD_VECTOR)

up OutOpt

Upwards orientation. This vector must be of unit length and perpendicular to the forwards vector. (FMOD_VECTOR)

See Also: Geometry::setRotation

Geometry::getScale

Retrieves the 3D scale of the object.

FMOD_RESULT Geometry::getScale(
  FMOD_VECTOR *scale
);

FMOD_RESULT FMOD_Geometry_GetScale(
  FMOD_GEOMETRY *geometry,
  FMOD_VECTOR *scale
);

RESULT Geometry.getScale(
  out VECTOR scale
);

Geometry.getScale(
  scale
);

scale Out

Scale value. (FMOD_VECTOR)

• Units: Linear
• Default: (1, 1, 1)

See Also: Geometry::setScale

Geometry::getUserData

Retrieves a user value associated with this object.

FMOD_RESULT Geometry::getUserData(
  void **userdata
);

FMOD_RESULT FMOD_Geometry_GetUserData(
  FMOD_GEOMETRY *geometry,
  void **userdata
);

RESULT Geometry.getUserData(
  out IntPtr userdata
);

Geometry.getUserData(
  userdata
);

userdata Out

Value stored on this object.

See Also: Geometry::setUserData

Geometry::release

Frees a geometry object and releases its memory.

FMOD_RESULT Geometry::release();

FMOD_RESULT FMOD_Geometry_Release(FMOD_GEOMETRY *geometry);

RESULT Geometry.release();

Geometry.release();

Geometry::save

Saves the geometry object as a serialized binary block to a user memory buffer.

FMOD_RESULT Geometry::save(
  void *data,
  int *datasize
);

FMOD_RESULT FMOD_Geometry_Save(
  FMOD_GEOMETRY *geometry,
  void *data,
  int *datasize
);

RESULT Geometry.save(
  IntPtr data,
  out int datasize
);

data OutOpt

Serialized geometry object. Specify null to have the datasize parameter return the size of the memory required for this saved object.

datasize Out

Size required to save this object when 'data' parameter is null. Otherwise ignored.

• Units: Bytes

Typical usage of this function is to call it twice - once to get the size of the data, then again to write the data to your pointer.

The data can be saved to a file if required and loaded later with System::loadGeometry.

See Also: System::createGeometry

Geometry::setActive

Sets whether an object is processed by the geometry engine.

FMOD_RESULT Geometry::setActive(
  bool active
);

FMOD_RESULT FMOD_Geometry_SetActive(
  FMOD_GEOMETRY *geometry,
  FMOD_BOOL active
);

RESULT Geometry.setActive(
  bool active
);

Geometry.setActive(
  active
);

active

Allow object to be processed by the geometry engine.

• Units: Boolean
• Default: True

See Also: Geometry::getActive

Geometry::setPolygonAttributes

Sets individual attributes for a polygon inside a geometry object.

FMOD_RESULT Geometry::setPolygonAttributes(
  int index,
  float directocclusion,
  float reverbocclusion,
  bool doublesided
);

FMOD_RESULT FMOD_Geometry_SetPolygonAttributes(
  FMOD_GEOMETRY *geometry,
  int index,
  float directocclusion,
  float reverbocclusion,
  FMOD_BOOL doublesided
);

RESULT Geometry.setPolygonAttributes(
  int index,
  float directocclusion,
  float reverbocclusion,
  bool doublesided
);

Geometry.setPolygonAttributes(
  index,
  directocclusion,
  reverbocclusion,
  doublesided
);

index

Polygon index.

• Range: [0, Geometry::getNumPolygons)

directocclusion

Occlusion factor of the polygon for the direct path where 0 represents no occlusion and 1 represents full occlusion.

• Range: [0, 1]
• Default: 0
• Units: Linear

reverbocclusion

Occlusion factor of the polygon for the reverb path where 0 represents no occlusion and 1 represents full occlusion.

• Range: [0, 1]
• Default: 0
• Units: Linear

doublesided

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.

• Units: Boolean

See Also: Geometry::getPolygonAttributes, Geometry::getNumPolygons

Geometry::setPolygonVertex

Alters the position of a polygon's vertex inside a geometry object.

FMOD_RESULT Geometry::setPolygonVertex(
  int index,
  int vertexindex,
  const FMOD_VECTOR *vertex
);

FMOD_RESULT FMOD_Geometry_SetPolygonVertex(
  FMOD_GEOMETRY *geometry,
  int index,
  int vertexindex,
  const FMOD_VECTOR *vertex
);

RESULT Geometry.setPolygonVertex(
  int index,
  int vertexindex,
  ref VECTOR vertex
);

Geometry.setPolygonVertex(
  index,
  vertexindex,
  vertex
);

index

Polygon index.

• Range: [0, Geometry::getNumPolygons)

vertexindex

Polygon vertex index.

• Range: [0, Geometry::getPolygonNumVertices (index) )

vertex

3D Position of the vertex. (FMOD_VECTOR)

• Units: Distance units

Vertices are relative to the position of the object. See Geometry::setPosition.

There may be some significant overhead with this function as it may cause some reconfiguration of internal data structures used to speed up sound-ray testing.

You may get better results if you want to modify your object by using Geometry::setPosition, Geometry::setScale and Geometry::setRotation.

See Also: Geometry::getPolygonNumVertices, Geometry::getPolygonNumVertices, Geometry::getNumPolygons

Geometry::setPosition

Sets the 3D position of the object.

FMOD_RESULT Geometry::setPosition(
  const FMOD_VECTOR *position
);

FMOD_RESULT FMOD_Geometry_SetPosition(
  FMOD_GEOMETRY *geometry,
  const FMOD_VECTOR *position
);

RESULT Geometry.setPosition(
  ref VECTOR position
);

Geometry.setPosition(
  position
);

position

3D position. (FMOD_VECTOR)

• Units: Distance units
• Default: (0, 0, 0)

Position is in world space.

See Also: Geometry::getPosition, Geometry::setRotation, Geometry::setScale

Geometry::setRotation

Sets the 3D orientation of the object.

FMOD_RESULT Geometry::setRotation(
  const FMOD_VECTOR *forward,
  const FMOD_VECTOR *up
);

FMOD_RESULT FMOD_Geometry_SetRotation(
  FMOD_GEOMETRY *geometry,
  const FMOD_VECTOR *forward,
  const FMOD_VECTOR *up
);

RESULT Geometry.setRotation(
  ref VECTOR forward,
  ref VECTOR up
);

Geometry.setRotation(
  forward,
  up
);

forward Opt

Forwards orientation. This vector must be of unit length and perpendicular to the up vector. (FMOD_VECTOR)

• Default: (0, 0, 1)

up Opt

Upwards orientation. This vector must be of unit length and perpendicular to the forwards vector. (FMOD_VECTOR)

• Default: (0, 1, 0)

See remarks in System::set3DListenerAttributes for more description on forward and up vectors.

See Also: Geometry::getRotation, Geometry::setPosition, Geometry::setScale

Geometry::setScale

Sets the 3D scale of the object.

FMOD_RESULT Geometry::setScale(
  const FMOD_VECTOR *scale
);

FMOD_RESULT FMOD_Geometry_SetScale(
  FMOD_GEOMETRY *geometry,
  const FMOD_VECTOR *scale
);

RESULT Geometry.setScale(
  ref VECTOR scale
);

Geometry.setScale(
  scale
);

scale

Scale value. (FMOD_VECTOR)

• Units: Linear
• Default: (1, 1, 1)

An object can be scaled/warped in all 3 dimensions separately using this function without having to modify polygon data.

See Also: Geometry::getScale, Geometry::setPosition, Geometry::setRotation

Geometry::setUserData

Sets a user value associated with this object.

FMOD_RESULT Geometry::setUserData(
  void *userdata
);

FMOD_RESULT FMOD_Geometry_SetUserData(
  FMOD_GEOMETRY *geometry,
  void *userdata
);

RESULT Geometry.setUserData(
  IntPtr userdata
);

Geometry.setUserData(
  userdata
);

userdata

Value stored on this object.

Associates some data with this object to give it context, it will be passed back via callbacks but otherwise remain untouched.

See Also: Geometry::getUserData