Browse Source

Write more 0.10.0 docs;

bjorn 7 years ago
parent
commit
8633575c9f

File diff suppressed because it is too large
+ 214 - 12
api/init.lua


+ 13 - 1
api/lovr/callbacks/conf.lua

@@ -28,7 +28,7 @@ return {
               description = 'An ordered list of preferred headset drivers.'
             },
             {
-              name = 'mirrored',
+              name = 'mirror',
               type = 'boolean',
               description = [[
                 Whether the desktop window should display a mirror of what's in the headset.
@@ -51,6 +51,11 @@ return {
               type = 'boolean',
               description = 'Whether the audio module should be enabled.'
             },
+            {
+              name = 'data',
+              type = 'boolean',
+              description = 'Whether the data module should be enabled.'
+            },
             {
               name = 'event',
               type = 'boolean',
@@ -81,6 +86,11 @@ return {
               type = 'boolean',
               description = 'Whether the physics module should be enabled.'
             },
+            {
+              name = 'thread',
+              type = 'boolean',
+              description = 'Whether the thread module should be enabled.'
+            },
             {
               name = 'timer',
               type = 'boolean',
@@ -164,11 +174,13 @@ return {
 
           -- Enable or disable different modules
           t.modules.audio = true
+          t.modules.data = true
           t.modules.event = true
           t.modules.graphics = true
           t.modules.headset = true
           t.modules.math = true
           t.modules.physics = true
+          t.modules.thread = true
           t.modules.timer = true
 
           -- Configure gamma correction

+ 1 - 7
api/lovr/callbacks/draw.lua

@@ -6,13 +6,7 @@ return {
     this function will be called twice per frame (once for each eye) and the function will instead
     draw to the headset's display.
   ]],
-  arguments = {
-    {
-      name = 'eye',
-      type = 'HeadsetEye',
-      description = 'The eye currently being rendered to.'
-    }
-  },
+  arguments = {},
   returns = {},
   related = {
     'lovr.headset.renderTo'

+ 15 - 12
api/lovr/callbacks/step.lua

@@ -23,31 +23,34 @@ return {
           if name == 'quit' and (not lovr.quit or not lovr.quit()) then
             return a
           end
-          lovr.handlers[name](a, b, c, d)
+          if lovr.handlers[name] then lovr.handlers[name](a, b, c, d) end
         end
 
         local dt = lovr.timer.step()
+        if lovr.headset then
+          lovr.headset.update(dt)
+        end
         if lovr.audio then
           lovr.audio.update()
-          if lovr.headset and lovr.headset.isPresent() then
+          if lovr.headset then
             lovr.audio.setOrientation(lovr.headset.getOrientation())
             lovr.audio.setPosition(lovr.headset.getPosition())
             lovr.audio.setVelocity(lovr.headset.getVelocity())
           end
         end
         if lovr.update then lovr.update(dt) end
-
-        lovr.graphics.clear()
-        lovr.graphics.origin()
-        if lovr.draw then
-          if lovr.headset and lovr.headset.isPresent() then
-            lovr.headset.renderTo(lovr.draw)
-          else
-            lovr.draw()
+        if lovr.graphics then
+          lovr.graphics.clear()
+          lovr.graphics.origin()
+          if lovr.draw then
+            if lovr.headset then
+              lovr.headset.renderTo(lovr.draw)
+            else
+              lovr.draw()
+            end
           end
+          lovr.graphics.present()
         end
-        lovr.graphics.present()
-
         lovr.timer.sleep(.001)
       end
     ]],

+ 57 - 0
api/lovr/graphics/Mesh/attachAttributes.lua

@@ -0,0 +1,57 @@
+return {
+  summary = 'Attach attributes from another Mesh onto this one.',
+  description = [[
+    Attaches attributes from another Mesh onto this one.  This can be used to share vertex data
+    across multiple meshes without duplicating the data, and can also be used for instanced
+    rendering by using the `divisor` parameter.
+  ]],
+  arguments = {
+    mesh = {
+      type = 'Mesh',
+      description = 'The Mesh to attach attributes from.'
+    },
+    divisor = {
+      type = 'number',
+      default = '0',
+      description = 'The attribute divisor for all attached attributes.'
+    },
+    attributes = {
+      type = 'table',
+      description = 'A table of attribute names to attach from the other Mesh.'
+    },
+    ['...'] = {
+      type = 'string',
+      description = 'The names of attributes to attach from the other Mesh.'
+    }
+  },
+  returns = {},
+  variants = {
+    {
+      description = 'Attach all attributes from the other mesh.',
+      arguments = { 'mesh', 'divisor' },
+      returns = {}
+    },
+    {
+      arguments = { 'mesh', 'divisor', '...' },
+      returns = {}
+    },
+    {
+      arguments = { 'mesh', 'divisor', 'attributes' },
+      returns = {}
+    }
+  },
+  notes = [[
+    The attribute divisor is a  number used to control how the attribute data relates to instancing.
+    If 0, then the attribute data is considered "per vertex", and each vertex will get the next
+    element of the attribute's data.  If the divisor 1 or more, then the attribute data is
+    considered "per instance", and every N instances will get the next element of the attribute
+    data.
+
+    To prevent cycles, it is not possible to attach attributes onto a Mesh that already has
+    attributes attached to a different Mesh.
+  ]],
+  related = {
+    'Mesh:detachAttributes',
+    'Mesh:drawInstanced'
+  }
+}

+ 37 - 0
api/lovr/graphics/Mesh/detachAttributes.lua

@@ -0,0 +1,37 @@
+return {
+  summary = 'Detach attributes that were attached from a different Mesh.',
+  description = 'Detaches attributes that were attached using `Mesh:attachAttributes`.',
+  arguments = {
+    mesh = {
+      type = 'Mesh',
+      description = 'A Mesh.  The names of all of the attributes from this Mesh will be detached.'
+    },
+    attributes = {
+      type = 'table',
+      description = 'A table of attribute names to detach.'
+    },
+    ['...'] = {
+      type = 'string',
+      description = 'The names of attributes to detach.'
+    }
+  },
+  returns = {},
+  variants = {
+    {
+      description = 'Detaches all attributes from the other mesh, by name.',
+      arguments = { 'mesh' },
+      returns = {}
+    },
+    {
+      arguments = { 'mesh', '...' },
+      returns = {}
+    },
+    {
+      arguments = { 'mesh', 'attributes' },
+      returns = {}
+    }
+  },
+  related = {
+    'Mesh:attachAttributes'
+  }
+}

+ 22 - 3
api/lovr/graphics/Mesh/setVertexMap.lua

@@ -8,11 +8,30 @@ return {
     specify the index of a vertex than it does to specify all of the data for a vertex.
   ]],
   arguments = {
-    {
-      name = 'map',
+    map = {
       type = 'table',
       description = 'The new vertex map.  Each element of the table is an index of a vertex.'
+    },
+    blob = {
+      type = 'Blob',
+      description = 'A Blob to use to update vertex data.'
+    },
+    size = {
+      type = 'number',
+      default = '4',
+      description = 'The size of each element of the Blob, in bytes.  Must be 2 or 4.'
     }
   },
-  returns = {}
+  returns = {},
+  variants = {
+    {
+      arguments = { 'map' },
+      returns = {}
+    },
+    {
+      description = 'This variant is much faster than the previous one, but is harder to use.',
+      arguments = { 'blob', 'size' },
+      returns = {}
+    }
+  }
 }

+ 26 - 4
api/lovr/graphics/Mesh/setVertices.lua

@@ -2,21 +2,43 @@ return {
   summary = 'Update multiple vertices in the Mesh.',
   description = 'Update multiple vertices in the Mesh.',
   arguments = {
-    {
-      name = 'vertices',
+    vertices = {
       type = 'table',
       description = 'The new set of vertices.'
     },
-    {
-      name = 'start',
+    vertexData = {
+      type = 'VertexData',
+      description = 'The VertexData object to use the vertices from.'
+    },
+    start = {
       type = 'number',
       default = '1',
       description = 'The index of the vertex to start replacing at.'
+    },
+    count = {
+      type = 'number',
+      default = 'nil',
+      description = [[
+        The number of vertices to replace.  If nil, all vertices in the table or VertexData will be
+        used.
+      ]]
     }
   },
   returns = {},
+  variants = {
+    {
+      arguments = { 'vertices', 'start', 'count' },
+      returns = {},
+    },
+    {
+      arguments = { 'vertexData', 'start', 'count' },
+      returns = {},
+    }
+  },
   notes = [[
     The start index plus the number of vertices in the table should not exceed the maximum size of
     the Mesh.
+
+    To use a VertexData, the Mesh and the VertexData must have the same format.
   ]]
 }

+ 21 - 2
api/lovr/graphics/Shader/init.lua

@@ -28,28 +28,47 @@ return {
 
         uniform mat4 lovrModel;
         uniform mat4 lovrView;
-        uniform mat4 lovrTransform;
-        uniform mat4 lovrNormalMatrix;
         uniform mat4 lovrProjection;
+        uniform mat4 lovrTransform; // Model-View matrix
+        uniform mat4 lovrNormalMatrix;
+        uniform mat4 lovrViews[2];  // View matrices for both eyes
+        uniform mat4 lovrTransforms[2]; // Model-View matrices for both eyes
+        uniform mat4 lovrProjections[2]; // Projection matrices for both eyes
+        uniform mat4 lovrNormalMatrices[2]; // Normal matrices for both eyes
         uniform float lovrPointSize;
         uniform mat4 lovrPose[48];
+        uniform int lovrIsStereo;
         in vec3 lovrPosition;
         in vec3 lovrNormal;
         in vec2 lovrTexCoord;
         in vec4 lovrVertexColor;
+        in vec3 lovrTangent;
         in ivec4 lovrBones;
         in vec4 lovrBoneWeights;
         out vec2 texCoord;
         out vec4 vertexColor;
+        flat out int lovrEye;
+
+    Additionally, the `lovrInstanceID` variable should be used to get the current instance ID when
+    using instanced rendering.
 
     Fragment shader header:
 
+        uniform float lovrMetalness;
+        uniform float lovrRoughness;
         uniform vec4 lovrColor;
         uniform vec4 lovrDiffuseColor;
+        uniform vec4 lovrEmissiveColor;
         uniform sampler2D lovrDiffuseTexture;
+        uniform sampler2D lovrEmissiveTexture;
+        uniform sampler2D lovrMetalnessTexture;
+        uniform sampler2D lovrRoughnessTexture;
+        uniform sampler2D lovrOcclusionTexture;
+        uniform sampler2D lovrNormalTexture;
         uniform samplerCube lovrEnvironmentTexture;
         in vec2 texCoord;
         in vec4 vertexColor;
+        flat in int lovrEye;
         in vec4 gl_FragCoord;
         out vec4 lovrFragColor;
   ]],

+ 2 - 0
api/lovr/graphics/Shader/send.lua

@@ -21,6 +21,8 @@ return {
     can be sent a `Transform` object.
 
     An error is thrown if the uniform does not exist or is not used in the shader.
+
+    `Blob`s can be used to pass arbitrary binary data to Shader variables.
   ]],
   example = {
     description = 'Updating a `vec3` uniform:',

+ 25 - 0
api/lovr/graphics/Texture/replacePixels.lua

@@ -0,0 +1,25 @@
+return {
+  summary = 'Replace pixels in the Texture using a TextureData object.',
+  description = 'Replaces pixels in the Texture, sourcing from a `TextureData` object.',
+  arguments = {
+    {
+      name = 'textureData',
+      type = 'TextureData',
+      description = [[
+        The TextureData containing the pixels to use.  Currently, the TextureData needs to have the
+        same dimensions as the source Texture.
+      ]]
+    },
+    {
+      name = 'slice',
+      type = 'number',
+      default = '1',
+      description = 'The slice to replace.  Not applicable for 2D textures.'
+    }
+  },
+  returns = {},
+  related = {
+    'TextureData:setPixel',
+    'TextureData'
+  }
+}

+ 8 - 0
api/lovr/graphics/newMesh.lua

@@ -28,6 +28,10 @@ return {
       type = 'table',
       description = 'A table of vertices.  Each vertex is a table containing the vertex data.'
     },
+    vertexData = {
+      type = 'VertexData',
+      description = 'The VertexData to load into the Mesh.'
+    },
     format = {
       type = 'table',
       description = 'A table describing the attribute format for the vertices.'
@@ -59,6 +63,10 @@ return {
     {
       arguments = { 'format', 'vertices', 'mode', 'usage' },
       returns = { 'mesh' }
+    },
+    {
+      arguments = { 'vertices', 'mode', 'usage' },
+      returns = { 'mesh' }
     }
   },
   notes = 'Once created, the size of the Mesh can\'t be changed.'

+ 2 - 2
api/lovr/headset/renderTo.lua

@@ -16,8 +16,8 @@ return {
       name = 'callback',
       type = 'function',
       description = [[
-        The function used to render.  It will be passed a string representing the
-        current eye that is being rendered to, either "left" or "right".
+        The function used to render.  Any functions called will render to the headset instead of to
+        the window.
       ]]
     }
   },

Some files were not shown because too many files changed in this diff