From e2ef9a89ad1e0e8aac625456a6300b0a05644c90 Mon Sep 17 00:00:00 2001 From: bjorn Date: Tue, 4 Oct 2016 12:10:25 -0700 Subject: [PATCH] Some documentation; --- README.md | 14 +++-- doc/API.md | 130 +++++++++++++++++++++++++++++++++++++++++++++++ doc/COMPILING.md | 70 +++++++++++++++++++++++++ 3 files changed, 209 insertions(+), 5 deletions(-) create mode 100644 doc/API.md create mode 100644 doc/COMPILING.md diff --git a/README.md b/README.md index 75a3d5d7..514fd660 100644 --- a/README.md +++ b/README.md @@ -25,13 +25,10 @@ end Drag the `myGame` folder onto a shortcut to `lovr.exe`. You should see a spinning purple cube! See instructions below on compiling `lovr.exe`. -Dependencies +Documentation --- -- LuaJIT -- GLFW (3.2+) and OpenGL (3.2+) -- assimp -- SteamVR (OpenVR) +Some rough reference documentation exists in [API.md](doc/API.md). Supported Hardware --- @@ -43,6 +40,13 @@ Support for other hardware will happen eventually. Compiling --- +### Dependencies + +- LuaJIT +- GLFW (3.2+) and OpenGL (3.2+) +- assimp +- SteamVR (OpenVR) + ### Windows (CMake) - Install [lovr-deps](https://github.com/bjornbytes/lovr-deps): diff --git a/doc/API.md b/doc/API.md new file mode 100644 index 00000000..a1422b02 --- /dev/null +++ b/doc/API.md @@ -0,0 +1,130 @@ +`lovr.headset` +--- + +- `isPresent = isPresent()` - Whether or not the headset is connected and available for use. +- `getType()` - "Vive" for the Vive or "Rift" for the Oculus Rift. Currently only Vive is + supported. +- `renderTo(callback)` - Render to the headset using a function. The callback function will be + called twice, once for each eye. This function sets the correct transformation and projection + matrices before rendering. +- `x, y, z = getPosition()` - Get the position of the headset in meters. +- `angle, axisX, axisY, axisZ = getOrientation()` - Get the orientation of the headset returned in + angle/axis format (radians). +- `vx, vy, vz = getVelocity()` - Get the velocity of the headset. +- `x, y, z = getAngularVelocity()` - Get the angular velocity of the headset. + `hand` is "left" or "right". +- `setClipDistance(number near, number far)` - Set the clip distance of the virtual camera. +- `near, far = getClipDistance()` - Retrieve the clip distance of the virutal camera. +- `width, depth = getTrackingSize()` - Dimensions for the rectangle enclosing the available play + area, in meters. +- `isVisible = isBoundsVisible()` - Whether or not the boundary grid is currently visible. +- `setBoundsVisible(boolean isVisible)` - Request the boundary grid to be shown or hidden. + +Controllers: + +- `Controller = lovr.headset.getController(string hand)` - Return a controller object for the specified hand. +- `isPresent = Controller:isPresent` - Whether or not the controller is connected and available for + use. +- `x, y, z = Controller:getPosition()` +- `angle, axisX, axisY, axisZ = Controller:getOrientation()` + +Note: The headset module requires SteamVR to properly function. It can be disabled using a +`conf.lua` file: + +``` +-- conf.lua +function lovr.conf(t) + t.modules.headset = false +end +``` + +`lovr.graphics` +--- + +Primitives: + +- `lovr.graphics.cube(mode, x, y, z, size, angle, axisX, axisY, axisZ)` + - `mode` is either "fill" or "line". + - `x`, `y`, `z` default to 0. + - `size` defaults to 1.0. + - `angle` is in radians. + - `axis` values should represent a normalized vector to rotate the cube around. +- `lovr.graphics.plane(mode, x, y, z, size, normalX, normalY, normalZ)` + - `mode` is either "fill" or "line". + - `x`, `y`, `z` default to 0. + - `size` defaults to 1.0. + - `normal` direction defaults to `(0, 1, 0)` (flat plane on the "ground"). +- `lovr.graphics.line(points)` + - Coordinates need `x`, `y`, and `z` components, and can be specified as arguments or as a single + table. + +Setup and transforms: + +- `reset()`, `clear(color, depth)`, `present()` - These are generally called automatically by + `lovr.run`. +- `push`, `pop`, `origin`, `translate(x, y, z)`, `rotate(angle, axisX, axisY, axisZ)`, `scale(x, y, z)` +- `setProjection(near, far, fov)` - FOV is in radians +- `getWidth`, `getHeight`, `getDimensions` - Return the dimensions of the window in pixels. + +Graphics state: All setters have corresponding getters + +- `setColor(r, g, b, a)` - Color channels are from 0 to 255. +- `setColorMask(r, g, b, a)` - Boolean values determine which color channels are manipulated when + drawing. +- `setScissor(x, y, w, h)` - Or use `nil` to disable the scissor. +- `setLineWidth(width)` - Currently at the whim of graphics driver support. +- `setPolygonWinding(winding)` - Either "clockwise" or "counterclockwise". +- `setCullingEnabled(isEnabled)` and `isCullingEnabled()` + +Shaders: + +- `Shader = lovr.graphics.newShader(string vertex, string fragment)` - Creates a new shader. Some + uniforms are automatically available: + - `lovrTransform` is a `mat4` containing the current View * Model matrix. + - `lovrProjection` is a `mat4` containing the current projection matrix. + - `lovrColor` is the color set by `lovr.graphics.setColor`. + - Source for the default shader: + +``` +shader = lovr.graphics.newShader([[ +void main() { + gl_Position = lovrProjection * lovrTransform * vec4(position.xyz, 1.0); +} +]], [[ +void main() { + color = lovrColor; +} +]]) +``` + +- `Shader:send(string uniformName, number/table value)` - Send a value to a Shader's uniform. Vectors and + matrices should be flat tables. + +Buffers: + +- `Buffer = lovr.graphics.newBuffer(size, mode, usage)` + - `size` is the number of vertices in the buffer. + - `mode` is the draw mode. Supported draw modes are "points", "strip", "triangles", and "fan". + The default draw mode is "fan". + - `usage` is a string indicating how the Buffer is intended to be used. It can be "static", + "dynamic", or "stream". The default is "dynamic". +- `Buffer:draw()` - Draws the buffer. +- `Buffer:setDrawMode(mode)` - Sets the draw mode. +- `Buffer:setVertex(index, x, y, z)` - Set the value of a vertex. +- `Buffer:setVertexMap(map)` - Set the draw order of the vertices. It is possible to re-use + indices. +- `Buffer:setDrawRange(start, count)` - Limits the vertices draw to a subset of the total. +- `Buffer:getVertexCount()` - Retrieve the number of vertices in the Buffer. + +`lovr.event` +--- + +- `poll` - Automatically called on every update by `lovr.run`. +- `quit` - Quits the game. + +`lovr.timer` +--- + +- `dt = step()` - Measures the time since this function was last called. This is called + automatically by `lovr.run` every tick and passed to `lovr.update`. +- `sleep(duration)` - Sleeps for the specified number of seconds. diff --git a/doc/COMPILING.md b/doc/COMPILING.md new file mode 100644 index 00000000..776c4a75 --- /dev/null +++ b/doc/COMPILING.md @@ -0,0 +1,70 @@ +Compiling +=== + +How to compile LÖVR from source. + +Dependencies +--- + +- LuaJIT +- GLFW (3.2+) and OpenGL (3.2+) and GLEW +- assimp (`lovr.model` and `lovr.graphics.newModel`) +- OpenVR (`lovr.headset`) + +Windows (Using CMake) +--- + +First, install [lovr-deps](https://github.com/bjornbytes/lovr-deps): + +```sh +cd lovr +git clone --recursive https://github.com/bjornbytes/lovr-deps deps +``` + +Next, build using the CMake GUI or using the CMake command line. + +```sh +mkdir build +cd build +cmake .. +``` + +This should output a Visual Studio solution, which can be built using Visual Studio. Or you can +just build it with CMake: + +```sh +cmake --build . +``` + +The executable will then exist at `/path/to/lovr/build/Debug/lovr.exe`. The recommended way to +create and run a game from this point is: + +- Create a shortcut to the `lovr.exe` executable somewhere convenient. +- Create a folder for your game: `MySuperAwesomeGame`. +- Create a `main.lua` file in the folder and put your code in there. +- Drag the `MySuperAwesomeGame` folder onto the shortcut to `lovr.exe`. + +### OSX (tup) + +Used for development, not generally recommended. + +One-time setup: + +```sh +cd lovr +git clone git@github.com:ValveSoftware/openvr .. +export DYLD_LIBRARY_PATH=`pwd`/../openvr/lib/osx32 +brew install assimp glfw3 luajit tup +``` + +Compiling: + +```sh +tup +``` + +Running a game: + +```sh +$ ./lovr /path/to/game +```