Module object3d

Basic utility for rendering a batch of 3-D polygons (an "object") to a texture, say for use in fills.

To use the plugin, add the following in build.settings:

plugins = {
   ["plugin.object3d"] = { publisherId = "com.xibalbastudios" },
   ["plugin.MemoryBlob"] = { publisherId = "com.xibalbastudios" }
 }

As shown, the (free) MemoryBlob is also a dependency. While not strictly necessary, the (also free) Bytemap plugin is the recommended way to provide the texture to display objects.

Sample code is available here.

The Bytes type—specified in a few of the bytemap methods—may be any object that implements ByteReader, including strings.

The current implementation is a veneer over a somewhat customized tinyrenderer.

From tinyrenderer's project page:

Tiny Renderer, https://github.com/ssloy/tinyrenderer Copyright Dmitry V. Sokolov

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.

Functions

New (w, h, has_alpha) Create a new Object3d.
Object3d:AddFace (...) DOCME
Object3d:AddNormal (x, y, z) DOCME
Object3d:AddUV (u, v) DOCME
Object3d:AddVertex (x, y, z) DOCME
Object3d:Clear () Wipe the texture (to black or clear) and z-buffer.
Object3d:GetBlob () Get the underlying (fixed-size) memory blob, e.g.
Object3d:GetBytes () Copy the current texture contents to a string.
Object3d:GetColor (px, py, pz, qx, qy, qz) Attempt to intersect a segment with a face and get the color where it hits.
Object3d:GetFaceVertexIndices (index) DOCME
Object3d:GetVertex (index) DOCME
Object3d:__len () Metamethod.
Object3d:Render () Render the current scene, clearing the previous contents first.
Object3d:SetCenter (Center) Set the center position.
Object3d:SetDiffuse (how, w, h[, comps=3]) DOCME
Object3d:SetEye (Eye) Set the eye position.
Object3d:SetLightDir (Direction) Set the light direction.
Object3d:SetNormalMap (bytes, w, h[, comps=3]) DOCME
Object3d:SetUp (Vector) Set the up vector.


Functions

New (w, h, has_alpha)
Create a new Object3d.

SURFACES: TEXTURE, Z-BUFFER CAMERA: EYE, LIGHT DIR, LOOK AT, UP SCENE: VERTEX, NORMAL, UV STREAMS

Parameters:

  • w int Texture width...
  • h int ...and height.
  • has_alpha bool Include an alpha channel? (Unnecessary if the background will be filled.)

Returns:

    Object3d or nil Object interface, or nil on error.
Object3d:AddFace (...)
DOCME

Parameters:

  • ... int triples Indices
Object3d:AddNormal (x, y, z)
DOCME

Parameters:

  • x number
  • y number
  • z number
Object3d:AddUV (u, v)
DOCME

Parameters:

  • u number
  • v number
Object3d:AddVertex (x, y, z)
DOCME

Parameters:

  • x number
  • y number
  • z number
Object3d:Clear ()
Wipe the texture (to black or clear) and z-buffer.
Object3d:GetBlob ()
Get the underlying (fixed-size) memory blob, e.g. to perform blob-specific operations on it.

Returns:

    MemoryBlob Blob.
Object3d:GetBytes ()
Copy the current texture contents to a string.

Returns:

    string A string of size w * h * ncomps, where w and h were supplied to New and ncomps is 3 or 4, the latter when has_alpha was supplied.
Object3d:GetColor (px, py, pz, qx, qy, qz)
Attempt to intersect a segment with a face and get the color where it hits.

Parameters:

  • px number First endpoint of segment, x-coordinate...
  • py number ...y...
  • pz number ...and z.
  • qx number Second endpoint, x-coordinate...
  • qy number ...y...
  • qz number ...and z.

Returns:

  1. r Red component at hit...
  2. g ...green component...
  3. b ...red component...
  4. a ...and alpha component. (Only returned if this channel exists. TODO: diffuse, normal, etc.)

Or

    nil, meaning the segment never intersected the face.
Object3d:GetFaceVertexIndices (index)
DOCME

Parameters:

  • index uint

Returns:

    ... face indices
Object3d:GetVertex (index)
DOCME

Parameters:

  • index uint

Returns:

  1. number Vertex x-coordinate...
  2. number ...y...
  3. number ...and z.
Object3d:__len ()
Metamethod.

Returns:

    uint Face count.
Object3d:Render ()
Render the current scene, clearing the previous contents first.

See also:

Object3d:SetCenter (Center)
Set the center position. (TODO: lookat)

Parameters:

  • Center number x-coordinate...
Object3d:SetDiffuse (how, w, h[, comps=3])
DOCME

Parameters:

  • how Bytes or nil "uvs", bytes, or nil to clear
  • w uint
  • h uint
  • comps uint (default 3)
Object3d:SetEye (Eye)
Set the eye position. (TODO: lookat)

Parameters:

  • Eye number x-coordinate...
Object3d:SetLightDir (Direction)
Set the light direction. (TODO: normal)

Parameters:

  • Direction number 's x-component...
Object3d:SetNormalMap (bytes, w, h[, comps=3])
DOCME

Parameters:

  • bytes Bytes or nil or nil to clear
  • w uint
  • h uint
  • comps uint (default 3)
Object3d:SetUp (Vector)
Set the up vector. (TODO: lookat)

Parameters:

  • Vector number 's x-component...
generated by LDoc 1.4.0