bjornbytes / lovr-docs Goto Github PK

relevant markdown is here.

https://github.com/bjornbytes/lovr-docs/blob/master/guides/Distribution.md
[link to htm](https://github.com/bjornbytes/lovr/blob/master/src/resources/lovr.html) in the distribution for webvr no longer exists

So people can read docs like the website, but locally.

small changes

• “torwards”
  https://lovr.org/docs/v0.15.0/Mat4:target

• “affect” should be “effect”
  https://lovr.org/docs/Collider:applyTorque

• :detectOverlaps should read :computeOverlaps
  https://lovr.org/docs/World:overlaps

• This page should list https://lovr.org/docs/World:newMeshCollider
  https://lovr.org/docs/Collider

• This setDimensions() function doesn’t actually exist; it should read setRadius()
  https://lovr.org/docs/SphereShape

• The equation at the bottom has a typo
  https://lovr.org/docs/Vec4:length

• Paragraph 1, last sentence, should specify that it's the center of the floor
  https://lovr.org/docs/lovr.headset

• Return value is wrong:
  https://lovr.org/docs/v0.15.0/lovr.math.newMat4
  https://lovr.org/docs/v0.15.0/lovr.math.mat4

• For people who follow tutorials by typing every example, the second code block should link to a monkey model:
  https://lovr.org/docs/v0.15.0/Callbacks_and_Modules

• This page has a broken link to this image:
  https://lovr.org/docs/v0.15.0/Simple_Lighting
  https://barelyconsciousgames.blogspot.com/2020/07/simple-lighting-for-lovr-phong-model-in.html

bigger changes

• These pages should clarify that :collide creates contact joints, and :update processes those joints
  https://lovr.org/docs/World:collide
  https://lovr.org/docs/World:update
  https://lovr.org/docs/v0.15.0/World

• It would be cool if this page said how it computes overlaps. Some questions I had while reading it:
  https://lovr.org/docs/World:computeOverlaps
  • Does it check collision between AABBs? If that's all I want, can I use it for that?
  • Does it use a fast algorithm, or should I avoid calling it many times per frame?
  • I think at some point, someone said that ODE uses spatial hashing – is this that?

• "Returns the original matrix" is misleading. This seems to be the default text on most vector pages. Might make sense to default to "returns the new matrix" or "returns the changed matrix" or something
  https://lovr.org/docs/Mat4:lookAt

These are super useful, it'd be nice to have them documented :)

It would be nice to be able to copy-paste a sudo apt install or pacman -S snippet to get all the necessary packages.

See also bjornbytes/lovr#510

The ShaderBlock:send notes mention passing tables of numbers, but the method signatures only suggest allowing Blobs:

For scalar or vector types, use tables of numbers or vec3s for each vector.

The signature of lovr.graphics.newShaderBlock doesn't describe the first argument, and it isn't demonstrated on that page, but it is shown on the ShaderBlock main page example.

See https://lovr.org/docs/lovr.graphics.newShaderBlock, the BufferUsage type for flags.usage isn't documented.

The postprocessing example fails with "bad argument #1 to 'fill' (Texture expected, got userdata)".

This part can be fixed with a two-line change.

 local function fullScreenDraw(source)
-  lovr.graphics.fill(source)
+  lovr.graphics.fill(source:getTexture())
 end

 -- ...

     screenShader:send("direction", {0, 4})
-    lovr.graphics.fill(tempCanvas[2]) -- On the final pass, render directly to the screen.
+    lovr.graphics.fill(tempCanvas[2]:getTexture()) -- On the final pass, render directly to the screen.
   end

Unfortunately (at least in the local viewer app on macOS) it renders completely incorrectly, flickering and horizontally duplicating the scene 16 or so times, presumably due to the double-wide texture rendering with the canvas.

• macOS 10.14.6
• LOVR 0.13.0 (Very Velociraptor)
• Intel Iris Graphics 6100 1536 MB

Actually LOVR returns inverted matrix, not original.

I didn't even realize that __mul and friends were implemented until I did it by accident. Now I'm struggling to figure out which operators can be done between which datatypes. It would be nice will a full documentation set of operators, valid operands, and results. Maybe it could just be a big table under lovr.math.

e.g.

function lovr.draw(pass)
  local width, height = lovr.system.getWindowDimensions()
  local projection = mat4():orthographic(0, width, 0, height, -10, 10)
  pass:setProjection(1, projection)
  pass:setViewPose(1, mat4():identity())
  pass:setDepthTest()

  local button = { x = 30, y = 30, w = 150, h = 60 }

  local mx, my = lovr.system.getMousePosition()
  local pressed = lovr.system.isMouseDown(1)
  local hovered = mx > button.x and mx < button.x + button.w and my > button.y and my < button.y + button.h

  pass:setColor(hovered and (pressed and { .25, .25, .27 } or { .2, .2, .22 }) or { .15, .15, .17 })
  pass:plane(button.x + button.w / 2, button.y + button.h / 2, 0, button.w, button.h)

  local font = lovr.graphics.getDefaultFont()
  font:setPixelDensity(1) -- set units to pixels instead of meters

  pass:setColor(1, 1, 1)
  pass:text('Hi!!!', button.x + button.w / 2, button.y + button.h / 2)
end

https://cs.android.com/android/platform/superproject/+/master:frameworks/base/tools/aapt/AaptAssets.cpp;l=60-61?q=AAPT_IGNORE

aapt will ignore directories that start with underscore among other things. This can mess up app packaging in confusing ways so maybe it should be mentioned. Alternatively I think lovr could try to pass an explicit ignore list to suppress this default behavior and do something a little more reasonable.

For example. you can lovr.math.mat4(lovr.headset.getPose(...)), which is not obvious because the documentation doesn't mention an overload of set() which takes x, y, z, a, ax, ay, az.

Link in https://lovr.org/docs/Simple_Lighting to https://barelyconsciousgames.com/lovr-phong.zip is incompatible with latest lovr.

Consider https://lovr.org/docs/v0.16.0/lovr.graphics.newBuffer, case (data, format).

location is the vertex attribute location of each field. This is used to match up each field with an attribute declared in a shader, and doesn't have any purpose when binding the buffer as a uniform or storage buffer. Any fields with a nil location will use an autoincrementing location starting at zero. Named locations are not currently supported, but may be added in the future. [my emphasis]

There are two problems here. First off, contra the bolded text, the sample code uses named locations: https://lovr.org/docs/Intro/Custom_Mesh

So, either the text or the sample code should be changed.

Secondly, which locations/location names are valid by default is not documented anywhere linked from here. This bit of documentation should include a link to https://lovr.org/docs/v0.16.0/Shaders#vertex-attributes

• C11 requires Windows SDK 2104 (maybe there is even a more specific version that has the stdalign.h fix).
• GCC version: 4.9
• clang version: 3.1

Need to add a list of existing plugins with some manual for building.

It's not really clear how the multiview rendering works, how Texture views should be use to render to specific layers/levels, etc.

Maybe an example too!

Along with the newSource changes

Instead of adding a description like "This function takes the same arguments as Vec3:set.", Please add argument and output values for the constructors.
This is very useful for auto-bindings. For example: Löwr

Not sure if it's 18 or 20

Since this impacts the ability to use Safari to read documentation, I think it makes sense not to embed Examples in Safari. Or at least hide them behind a play button.

Tested in macOS Monterey 12.2.1, on this Intel Mac.

These don’t crash:

Intro

• Hello World
• Spinning Cube
• 3D Model
• 360 Photo
• Tracked Hands

Interaction

• Controller Models (doesn’t render, but doesn’t crash)
• Hand Tracking (doesn’t render, but doesn’t crash)

Locomotion

• Environment
• Grid
• Skybox

Lighting

Animation

Physics

• Boxes
• Hand Physics
• Saloon Door

Audio

• Playback (doesn’t play, but doesn’t crash)
• Spatialization
• Sine Wave Generator (doesn’t play, but doesn’t crash)

Effects

• Stereo Image
• Cubemap Texturing

UI

Optimization

• Instancing (freezes for a few minutes, and just renders black eventually, but doesn’t crash)
• Mask (doesn’t render, but doesn’t crash)

Debugging

These crash:

Intro

• Shapes
• Thread
• Custom Mesh

Interaction

• Pointer
• Pointer UI
• Physics Pointer
• Dragging

Locomotion

• Basic Thumbsticks
• Teleportation Flat
• Teleportation Colliders
• Walking In Place

Environment

• Terrain - Heightmap (technically this eats my GPU and freezes my computer, but doesn’t crash)
• Terrain - Procedural (technically this eats my GPU and freezes my computer, but doesn’t crash)

Lighting

• PBR Materials
• Animation
• Playback
• 2 Bone IK

Physics

• Drawing Colliders
• Newtons Cradle
• Wrecking Ball
• Zip Line

Audio

• Directivity
• Mute (doesn’t play; crashes after a few seconds)

Effects

• Blur

UI

• Spectator Camera
• Window HUD

Optimization

Debugging

• FPS Controls (displays an error for a second, then crashes)
• Raw Input (crashes after a few seconds)

blit, clear, read, copy, etc.

As of the 0.16 docs, the only way to search the docs is to just start typing. Any keystroke is interpreted as an attempt to initiate a search. While this is very interesting, it has two problems:

• It is not very discoverable. I assumed doc search had been removed until I activated it by accident
• There is no way to activate it on mobile— at all

Expected behavior: There should be a magnifying glass button or "search" link somewhere that kicks open the search prompt.

See bjornbytes/lovr#575.

• How is the duration of an animation calculated?
• Do animation timestamps wrap around once they exceed the duration? Or is the final pose held?
• What happens if the keyframes for the animation don't start at zero?

If you're on a page like lovr.math.quat, if you want to jump back to lovr.math you have to scroll down to the "Related" section, which sucks. You should be able to click lovr in the header to go to the lovr page, or math to go to the lovr.math page. For methods on objects, you would click the object name to go to the object's page. It's a sneaky way of implementing "breadcrumb" navigation. Maybe too sneaky...

Make docs work on phones

Left over from when it was an overload of newTexture

In many places, the LÖVR docs mention that functions take or return a table containing some information, but they don't say what's in the table, just table, leaving me confused about how to access the contents. In all these cases it would be very useful to document the shape(s) of the tables.

Would be cool

Fog example would be useful in the Lighting section

It only specifies Windows/macOS, it should have Linux/Android/emscripten as well

I think the documentation for functions that have different variations isn't clear. Take Pass:plane as an example. The API documentation states that the transform parameter is a Mat4, or alternatively "can be provided as a position, 2-component scale, and rotation using a combination of Vectors, and numbers.". Would be nice to see each variant form explicitly documented, e.g., Pass:plane( pos_x, pos_y, pos_z, scale_x, scale_y, quat_x, quat_y, quat_z, quat_w, ... ) (if indeed that's an accepted form, i'm not sure...)

AttributeType page doesn't mention that byte/ubyte are normalized

e.g.

function lovr.draw(pass)
  local width, height = pass:getDimensions()
  pass:setProjection(1, mat4():orthographic(width, height, -1, 1))
  pass:setViewPose(1, mat4())

  local font = lovr.graphics.getDefaultFont()
  font:setPixelDensity(1)

  pass:text('hi', width / 2, height / 2, 0, 1)
end

There is Window_HUD but it's not a small snippet like this

I dunno if this is deliberate or just a recent addition you haven't had time to document it yet; I was calling it as self.collider:setPose(self.transform:unpack()), THEN noticed it's not in the docs and I had just assumed it exists, THEN noticed that that'll send scale as rotation args and be completely wrong, so yeah 😅

Hi,

Excellent job on this framework, I really love your website and docs as well, may I ask how do you generate all website + docs?

Thanks

(Maybe there should be a script that checks that all documented functions actually exist, either by probing a live lovr table or parsing the luaL_Reg entries in the C code)