SDK Geometry
From Kraytracing Wiki
Contents |
Introduction
To define a geometry in Kray script use shape command. This only defines geometry, but does not add it to scene. To add it to scene you need to connect shape with blend and surface. To do this use object
Example:
shape my_shape,.... // shape definition here surface my_surface,... // definition of surface here blend my_blend,... // blend object my_shape,my_surface,my_blend; // this adds geometry to scene
Triangles
Adding triangles directly using SDK
Triangles can be added to Kray scene using kray->addTriangle() function. This is the fastest way of doing that.
Adding triangles using script
Triangles can be defined from script level too (not recommended, when there is plenty of them on scene, use SDK directly in such cases)
Examples:
shape my_triangle,triangle,(0,0,0),(1,0,0),(0,1,0); // creates triangle with given vertex coords
shape my_triangle,uvtriangle,(0,0,0),(1,0,0),(0,1,0),5; // creates triangle with UV mapping enabled, 5 is a UV map index
shape my_triangle,inttriangle,(0,0,0),(1,0,0),(0,1,0),5,(0,0,-1),(0,0.7,-0.7),(0,0,-1); // creates triangle with UV mapping enabled and normal vector interpolation. (0,0,-1),(0,0.7,-0.7),(0,0,-1) are normal vectors at each triangle vertex.
There are also signle sided version of triangle primitives with ss suffix : triangless,uvtriangless,inttriangless.
Other geometric primitives
Rectangles
shape my_rectangle,square,(10,0,0),(1,0,0),(0,2,0);
Its called square, but actually it can be a rectangle. This creates rectangle object named my_rectangle with corner coords (10,0,0) (10+1,0,0) (10+1,0+2,0) (10,0+2,0)
Adding polygon mesh
Kray API provides tools for adding polygon mesh to a scene. A mesh consist of points and polygons. Points is simply a vertexmap (you must create it before creating mesh). To add polys to the mesh use meshaddpoly.
Here is an example script with comments:
vertexmap points,3,0,4; // vertex map dimension=3, point index start at 0, end at 4 (4 points total) vertexdata points,0,0,0,0; // vertex 0 is (0,0,0) vertexdata points,1,1,0,0; // vertex 1 is (1,0,0) vertexdata points,2,1,1,0; // vertex 2 is (1,1,0) vertexdata points,3,0,1,0; // vertex 3 is (0,1,0) mesh mymesh; // create mesh object named "mymesh" meshpoints mymesh,points; // connect vertexmap "points" to "mymesh" meshaddpoly mymesh,0,3,0,2,1; // first 0 is poly tag, add 3-gon (0,0,0) (1,1,0) (1,0,0) meshaddpoly mymesh,0,3,0,3,2; // first 0 is poly tag, add 3-gon (0,0,0) (0,1,0) (1,1,0) /meshaddpoly mymesh,0,4,3,2,1,0; // first 0 is poly tag, add 4-gon with vertex indices 3,2,1,0 material mat,diffuse,0.8; material mat,reflection,0.2; var mesh_flags,0; // bit flags for polygon group and mesh // meaning: // +1 single_sided polygon (KRAY_ADD_FLAG_SINGLESIDED on C API level) // +2 need uv (KRAY_ADD_FLAG_NEEDUV) // +0x1000 try to convert triangle pair into square (more effective LEM) (KRAY_ADD_FLAG_CONVERT_TO_SQUARE) meshtag mymesh,0,material,mat; meshtag mymesh,0,smoothing,0,0; // first param is smoothing group, second maximum smoothing angle meshtag mymesh,0,flags,mesh_flags; objectset mesh,(0,0,0),<>,mymesh,mesh_flags; // add mesh to scene // some environment background sky,(1,1,1),(0,0,1),(0,0,0),(0,1,0); light point,(-4,-3,-10),(1,1,1); // camera camera picture,400,300,300,(0,0,-3),<>;
If you want to assign LEM groups to polys use
meshaddpolygroup <mesh name>,<LEM group>,<surface tag>,<n-gon>,<vertex index 1>,<vertex index 2>,...
instead of
meshaddpoly <mesh name>,<surface tag>,<n-gon>,<vertex index 1>,<vertex index 2>,...
Polygon normal is computed based on vertex order, but if your vertex order is random you can provide polygon normal. It this case syntax is following:
meshaddpolynormal <mesh name>,<normal_vector>,<LEM group>,<surface tag>,<n-gon>,<vertex index 1>,<vertex index 2>,...
<normal_vector> must be enclosed with quotes for example (1,0,0).
LEM groups can be assigned automatically (connected parts of mesh become a group) if you set KRAY_ADD_FLAG_AUTO_GROUPS flags for objectset mesh,.... Automatic grouping works only on that part of mesh which group is unassigned (group==0). Manually assigned polygons are excluded from automatic grouping.
Another way of controlling LEM groups is via material settings. If a poly does not have group assigned (or its group is 0), material LEM group is used.
Vertex normal maps
By default mesh computes normals by itself (including normal smoothing - Phong interpolation), but instead of that you can provide a normal map for a mesh. There are 2 ways of adding normal map.
Per vertex normal map
meshpointnormals meshname,vertexmapname;
Example (adds normal map to mesh add example above):
vertexmap normals,3,0,4; // vertex map dimension=3, point index start at 0, end at 4
// (4 points total, same size as points vertexmap)
vertexdata normals,0,0,0,1; // normal of vertex 0 is (0,0,1)
vertexdata normals,1,0,0,1; // normal of vertex 1 is (0,0,1)
vertexdata normals,2,0,0,1; // normal of vertex 2 is (0,0,1)
vertexdata normals,3,0,0.7,0.7; // normal of vertex 3 is (0,0.7,0.7)
meshpointnormals mymesh,normals;
Vertex map size must be equal to number of points in the mesh.
Per polygon normal map
meshpolynormals meshname,vertexmapname;
Vertex map size must be equal to total number of vertices of polygons in the mesh. For example if your mesh is made of 5 triangles and 6 quads. Its size must be 5*3+6*4=39
Mesh tags
Mesh tag command describes poly tags. Each polygon added with meshaddpoly has a tag number (0 in example below)
meshaddpoly mymesh,0,3,1,2,3; // first param after mesh name is poly tag
To describe a tag, meshtag command is used. meshtag connects material with poly tag:
meshtag mymesh,0,material,mat; // mat is material name
It controls mesh normal vector smoothing:
meshtag mymesh,0,smoothing,0,0; // first param is smoothing group, second maximum smoothing angle in radians
It also has various bit flags:
var KRAY_ADD_FLAG_SINGLESIDED,0x1 // do we want single sided polygon? var KRAY_ADD_FLAG_NEEDUV,0x2 // do we use UV mapping on this polygon? var KRAY_ADD_FLAG_INVISIBLE,0x10 // do not add geometry to scene (hidden poly) var KRAY_ADD_FLAG_CONVERT_TO_SQUARE,0x1000 // find triangle pairs that makes a rectangle and add rectangle to the scene (useful for rectangle area lights) var KRAY_ADD_FLAG_AUTO_GROUPS,0x2000 // adding automatic groups to polygons (LEM groups) var KRAY_ADD_FLAG_AUTO_NORMALSIDE,0x4000 // makes polygon facing the same direction as given in vertex normal table var KRAY_ADD_FLAG_INSTANCE,0x8000 // set if your object will be instanced meshtag mymesh,0,flags,KRAY_ADD_FLAG_SINGLESIDED+KRAY_ADD_FLAG_CONVERT_TO_SQUARE;
Using C API
meshaddpolygroup has its faster C API counterpart. int kray->addPolyToMesh(KrayMesh mesh_handle,size_t ngon,int poly_tag,size_t *vertex_indices,int group=0). Mesh must be created first with script. Its handle can be obtained with kray->getObjectByName(). Function returns 1 when poly was add or 0 when adding poly failed (no memory)
You can also use kray->getObjectByName() to get pointer to vertex map and fill vertex map (points, normals, ...) directly from C level.
For details about functions check C API section.
