Browse Source

Pool docs;

bjorn 6 years ago
parent
commit
4aeabd7fb6

+ 12 - 0
api/lovr/math/Pool/drain.lua

@@ -0,0 +1,12 @@
+return {
+  summary = 'Drain the Pool.',
+  description = [[
+    Drains the Pool, invalidating all vectors that it has allocated and resetting its memory usage.
+  ]],
+  arguments = {},
+  returns = {},
+  related = {
+    'Pool:getUsage',
+    'Pool:getSize'
+  }
+}

+ 16 - 0
api/lovr/math/Pool/getSize.lua

@@ -0,0 +1,16 @@
+return {
+  summary = 'Get the size of the Pool.',
+  description = 'Returns the size of the Pool, in bytes.',
+  arguments = {},
+  returns = {
+    {
+      name = 'size',
+      type = 'number',
+      description = 'The size of the Pool.'
+    }
+  },
+  related = {
+    'Pool:getUsage',
+    'Pool:drain'
+  }
+}

+ 20 - 0
api/lovr/math/Pool/getUsage.lua

@@ -0,0 +1,20 @@
+return {
+  summary = 'Get the Pool\'s memory usage.',
+  description = 'Returns the amount of memory current in use by the Pool.',
+  arguments = {},
+  returns = {
+    {
+      name = 'size',
+      type = 'number',
+      description = 'The size of the Pool.'
+    }
+  },
+  notes = [[
+    `Pool:drain` can be used to reset the usage to zero (and invalidate vectors that have been
+    allocated from the Pool).
+  ]],
+  related = {
+    'Pool:getSize',
+    'Pool:drain'
+  }
+}

+ 2 - 2
api/lovr/math/Pool/init.lua

@@ -1,5 +1,5 @@
 return {
 return {
-  summary = 'A Pool of vectors objects.',
+  summary = 'A Pool of vector objects.',
   description = [[
   description = [[
     A Pool is an object that is used to allocate vectors, matrices, and quaternions.  Pools exist
     A Pool is an object that is used to allocate vectors, matrices, and quaternions.  Pools exist
     mainly for efficiency -- allocating tiny bits of memory for every single vector can lead to
     mainly for efficiency -- allocating tiny bits of memory for every single vector can lead to
@@ -24,5 +24,5 @@ return {
     like `lovr.math.vec3` or `lovr.math.mat4`.  These vectors are temporary vectors that will be
     like `lovr.math.vec3` or `lovr.math.mat4`.  These vectors are temporary vectors that will be
     drained at the end of the frame!  The default Pool is resizable.
     drained at the end of the frame!  The default Pool is resizable.
   ]],
   ]],
-  constructor = 'lovr.math.newPool',
+  constructor = 'lovr.math.newPool'
 }
 }

+ 60 - 0
api/lovr/math/Pool/mat4.lua

@@ -0,0 +1,60 @@
+return {
+  summary = 'Get a new mat4.',
+  description = 'Allocates a new `mat4` from the Pool and returns it.',
+  arguments = {
+    n = {
+      type = 'mat4',
+      description = 'An existing matrix to copy the values from.'
+    },
+    position = {
+      type = 'vec3',
+      default = '0, 0, 0',
+      description = 'The initial translation of the matrix.'
+    },
+    scale = {
+      type = 'vec3',
+      default = '1, 1, 1',
+      description = 'The initial scale of the matrix.'
+    },
+    rotation = {
+      type = 'quat',
+      default = '0, 0, 0, 0'<
+      description = 'The initial rotation of the matrix.'
+    }
+    ['...'] = {
+      type = 'number',
+      description = '16 numbers to use as the raw values of the matrix (column-major).'
+    }
+  },
+  returns = {
+    m = {
+      type = 'mat4',
+      description = 'The new matrix.'
+    }
+  },
+  variants = {
+    {
+      description = 'Returns an identity matrix.',
+      arguments = {},
+      returns = { 'm' }
+    },
+    {
+      arguments = { 'n' },
+      returns = { 'm' }
+    },
+    {
+      arguments = { 'position', 'scale', 'rotation' },
+      returns = { 'm' }
+    },
+    {
+      arguments = { '...' },
+      returns = { 'm' }
+    }
+  },
+  related = {
+    'Pool:vec3',
+    'Pool:quat',
+    'lovr.math.mat4',
+    'mat4'
+  }
+}

+ 90 - 0
api/lovr/math/Pool/quat.lua

@@ -0,0 +1,90 @@
+return {
+  summary = 'Get a new quat.',
+  description = 'Allocates a new `quat` from the Pool and returns it.',
+  arguments = {
+    angle = {
+      default = '0',
+      description = 'The angle to use for the rotation, in radians.'
+    },
+    ax = {
+      type = 'number',
+      default = '0',
+      description = 'The x component of the axis of rotation.'
+    },
+    ay = {
+      type = 'number',
+      default = '0',
+      description = 'The y component of the axis of rotation.'
+    },
+    az = {
+      type = 'number',
+      default = '0',
+      description = 'The z component of the axis of rotation.'
+    },
+    axis = {
+      type = 'vec3',
+      description = 'The axis of rotation (does not need to be normalized).'
+    },
+    raw = {
+      type = 'boolean',
+      default = 'false',
+      description = 'Whether the components should be interpreted as raw `(x, y, z, w)` components.'
+    },
+    v = {
+      type = 'vec3',
+      description = 'A normalized direction vector.'
+    },
+    u = {
+      type = 'vec3',
+      description = 'Another normalized direction vector.'
+    },
+    r = {
+      type = 'quat',
+      description = 'An existing quaternion to copy the values from.'
+    },
+    m = {
+      type = 'mat4',
+      description = 'A matrix to use the rotation from.'
+    }
+  },
+  returns = {
+    q = {
+      type = 'quat',
+      description = 'The new quaternion.'
+    }
+  },
+  variants = {
+    {
+      arguments = { 'angle', 'ax', 'ay', 'az', 'raw' },
+      returns = { 'q' }
+    },
+    {
+      arguments = { 'angle', 'axis' },
+      returns = { 'q' }
+    },
+    {
+      arguments = { 'r' },
+      returns = { 'q' }
+    },
+    {
+      description = 'Creates a quaternion from a direction vector.'
+      arguments = { 'v' },
+      returns = { 'q' }
+    }<
+    {
+      description = 'Creates a quaternion representing the rotation between two vectors.'
+      arguments = { 'v', 'u' },
+      returns = { 'q' }
+    }<
+    {
+      arguments = { 'm' },
+      returns = { 'q' }
+    }
+  },
+  related = {
+    'Pool:vec3',
+    'Pool:mat4',
+    'lovr.math.quat',
+    'quat'
+  }
+}