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:
- 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.
- Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
- 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:
- 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:
- r Red component at hit...
- g ...green component...
- b ...red component...
- 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:
- number Vertex x-coordinate...
- number ...y...
- 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...