|
|
Simple Isometric Graphics Library
The Simple Isometric Graphics Library package is an extension for Stencyl development environment. It provides an API for rendering and manipulating simple geometric solids in an isometric perspective.
General Discussion
The same basic vocabulary is used for this extension as is used in Isometric Mathematics Extension. Namely, "grid coordinates" refer to the coordinates within the 3D world, where as "scene coordinates" refer to the 2D scene plane. The same math is used in both extensions, as are the same conventions:
- The x-axis is projected right and down from the origin.
- The y-axis is projected left and down from the origin.
- The z-axis is projected straight up from the origin.
- The origin of any solid is the upper-left corner of its base (minimum x, y, and z coordinates).
Solids are composed of faces, and faces are defined by their vertices. Creating and manipulating simple solids is easy. However, rendering complex scenes will be a challenge. The difficulty is rendering the solids in the correct order, so that illusion of depth is preserved. You do not want solids far away to be rendered on top of solids that are closer.
It is up to the user of this extension to determine the best method for organizing figures in their 3D world. A few ideas are discussed in this thread in the Stencyl community forums.
One tool that might be particularly helpful is the 'sort renderable faces' function (and associated block). The faces that compose a solid are sorted when it is rotated. However, for complex scenes, all the faces may need to be sorted in one large list. The function getRenderableFaces will pull the faces that are not completely hidden by the solid itself, and return them in an array. This array can be joined with similar arrays from other solids. The function sortRenderableFaces will sort the array, then each element of the array can be rendered via the doRenderFace function.
Integration with Stencyl's palette: Because no default attribute type is available for solids, the "anything" type attribute is used for solids, faces, and vertices. The user will need to take caution in never passing the wrong type of figure to a function. In some cases, each function (in "code mode") can accept either solids or faces. However, the version of the functions called by blocks are more restrictive.
Advanced functions: Several functions are provided by the API, but not in block form. These are usually functions that would require custom rendering routines or are provided so a developer can extend the extension itself. In other cases, block versions will be made available in later revisions of this extension.
Quick Function Reference
Function | | Description |
setOriginX
setOriginY | | Sets the coordinates of the origin. The origin denotes the (x,y) scene coordinates for which the grid origin (0,0,0) is mapped to.
 |
| |
setScaleX
setScaleY
setScaleZ | | Sets the axis scalars which stretch or compress the rendering along the specified axis. Only the render is affected, not the coordinates of any objects.
 |
| |
setLightScalar | | Sets the lighting contrast. Value must be set between 0 and 1.
 |
| |
setLightDirection | | Sets the direction of the light vector. Note that the vector will automatically be normalized.
 |
| |
setOffsetX
setOffsetY
setOffsetZ | | Add the specified value to the X, Y, or Z coordinate of every vertex in the specified solid. This action affects the rendering only, and not the solid's actual coordinates.
 |
| |
doRender | | Renders the specified solid.
 |
| |
doRenderFace | | Renders the specified face.
 |
| |
makeRectangularSolid2
makePyramid2 | | Creates a solid at the origin with unit length, width, and depth.
 |
| |
doSetX
doSetY
doSetZ | | Sets the grid position of the solid.
 |
| |
doTranslate | | Translates the specified solid in the given x, y, and z directions.
 |
| |
doRotateX2
doRotateY2
doRotateZ2 | | Rotate a solid about the specified point and with respect to the specified axis. Note that 3D rotations are not commutative.
 |
| |
setWidth
setHeight
setDepth | | Sets the size of the specified solid, as applicable. For pyramids, depth is the distance between the base and the point.
 |
| |
doSetColor | | Sets the color of the solid.
 |
| |
getRenderableFaces | | Returns an array containing all the faces of a solid which will be rendered. The renderable faces are computed when a solid is initialized or rotated. Faces will be ordered from back to forward.
 |
| |
sortRenderableFaces | | Arranges an array of faces in order of depth. This array can be a union of arrays returned by the function 'getRenderableFaces'
 |
| |
|
