Kray3 SDK/Defining geometry

From Kray
Jump to: navigation, search

Creating polygon mesh

Polygon mesh is flexible and popular way of representing 3d model. To build a mesh in Kray you need to create a 3-dimensional vertexMap object with all mesh vertices and then create mesh object with list of polygons.

Lets create a simple box (cube). First lets define box corners. We need to create a 3-dimensional vertexMap object.

<syntaxhighlight> vertexMap boxVertices,3; </syntaxhighlight>

Our object is named 'boxVertices' and has dimension of 3. Now we need to create vertices which are simply 3d vectors with given id.

<syntaxhighlight> vertex3d boxVertices,0,(-1,-1,-1); vertex3d boxVertices,1,(-1,-1,1); vertex3d boxVertices,2,(-1,1,-1); vertex3d boxVertices,3,(-1,1,1); vertex3d boxVertices,4,(1,-1,-1); vertex3d boxVertices,5,(1,-1,1); vertex3d boxVertices,6,(1,1,-1); vertex3d boxVertices,7,(1,1,1);

</syntaxhighlight> Now 'boxVerices' vertexMap has 8 vertices (points) which are corners of a box I'm going to create. Its time to connect vertices into polygons. First we create mesh object. <syntaxhighlight> mesh boxMesh; // boxMesh is our name for an object </syntaxhighlight>

Then we connect previously created vertexMap to mesh ...

<syntaxhighlight> meshOp boxMesh,points,boxVertices; </syntaxhighlight>

... and create 4-gons - walls of our box.

<syntaxhighlight> meshAddPoly boxMesh,0,{0,2,6,4}; meshAddPoly boxMesh,0,{5,7,3,1}; meshAddPoly boxMesh,0,{1,3,2,0}; meshAddPoly boxMesh,0,{4,6,7,5}; meshAddPoly boxMesh,0,{0,4,5,1}; meshAddPoly boxMesh,0,{3,7,6,2}; </syntaxhighlight>

{0,2,6,4} means that a polygon will have 4 points of id 0,2,6,4. If we look at vertex list this points corresponds to positions (-1,-1,-1),(-1,1,-1),(1,1,-1),(1,-1,-1). Number of vertex ids provided determines number of polygon vertices. So

<syntaxhighlight> meshAddPoly boxMesh,0,{0,2,6}; </syntaxhighlight>

would create a triangle of vertices (-1,-1,-1),(-1,1,-1),(1,1,-1). Of course we are not limited to quads and triangles. Any n-gon can be created this way, but you need to pay attention that all n-gon points lay on the same plane. Order of vertices determines its facing direction. {0,2,6,4} is the same polygon as {4,6,2,0}, but facing opposite direction.

Each meshAddPoly line contains mysterious 0. This is index to materials table and since we don't yet have materials table here its simply ignored. This will be explained in next tutorial.

Ok. We have defined a mesh, but its not yet added to Kray scene, so it will not show on rendering. We need to create an object group and attach mesh to it.

<syntaxhighlight> group add; group attachset,mesh,(0,0,3.5),<12,53,43>,boxMesh,0; </syntaxhighlight>

Object group is logical part of scene. To modify Kray scene we operate on primitive groups rather than single primitives. When scene is updated groups can be added, removed or replaced with different geometry. You can also update material within a group, or make a group an instance and clone geometry. Those topics will be covered in dedicated tutorials.

(0,0,3.5) is a mesh position in world coordinated (default camera is in (0,0,0) position and looks to +Z axis). <12,53,43> is mesh orientation - some random angles, so we can see more than just a front face of a box.

Now we can merely render a black box on a black background which actually is impossible to distinguish from a black background without a black box, so we need to add

<syntaxhighlight> lightAdd point,(-1,-1,-2),(1,1,1); // white point light at position (-1,-1,-2) background sky,(0.4,0.8,0.9),(0,0,0),(1,1,1),(0,1,0); // gradient background </syntaxhighlight>

And now we can render everything.

<syntaxhighlight> render; </syntaxhighlight>

Whole box rendering script below.

<include highlight="kray3" src="/pub/kray3_script/mesh/box_mesh.kray"></include>{{#ifeq: 1|1|

Run in KrayLive|}}

Low level geometry handling

Since Kray is a raytracer its not limited to polygons only. There are other primitives available via low level API (complete list in objectAdd command reference). Low level objects (shape, surface, blend, texture) are used directly for rendering, while high level objects (mesh, material, metatexture) are more convenient to use and converted to low level objects at preprocessing stage (mesh->shapes material->surface+blend metatexture->texture). Low level API is harder to use and its recommended for more advanced users.

Using low level geometry objects (shape) forces us to use low level material description objects (surface, blend, texture). Surface object is a shader for photon and camera rays. Blend is used for shadows casting (shadow rays shader). Texture is low level equivalent of metatexture object and describes surface properties like color and can vary in space.

Here is a simple example how to create a scene with low level API:

<include highlight="kray3" src="/pub/kray3_script/lowlevel/ll_geom.kray"></include>{{#ifeq: 1|1|

Run in KrayLive|}}