Styrofoam IFS - Raytracer

The program raytrace_cl_cpp.exe can be used as a standalone raytracer for point-clouds.

Command line options

raytrace_cl_cpp.exe configfile cachelistfile ouputfile scenefile anim

Example: raytrace_cl_cpp.exe "C:\Users\Per\Documents\StyrofoamIFS\user.config" "C:\Users\Per\Documents\StyrofoamIFS\cache\_raytrace_cl_parameters.txt" "C:\Users\Per\Documents\StyrofoamIFS\autosave\autosave_test.png" "C:\Users\Per\Documents\StyrofoamIFS\ifs\lo-res.scene" 0

configfile is the path to the xml-file file that StyrofoamIFS automatically creates. It contains the dialog-options. In a normal run, the file is called user.config and is saved directly in the StyrofoamIFS folder.

cachelistfile is the path to file conataining the list of cache-files that should be raytraced. In a normal run, the file is called _raytrace_cl_parameters.txt and is saved in the cache folder.

ouputfile is the path to the png file that will be created. In a normal run, the file is called autosave_todays date.png and is saved in the autosave folder. Png is the only format supported.

scenefile is the path to the scene file that will be used for raytracing. This file is manually edited by you in a normal run. StyrofoamIFS comes with a few examples. In a normal run these are placed in the ifs folder. See documentation of .scene files for more info.

anim is the value of the parameter anim that can be used in the .scene file. This must be a numerical integer value. See documentation of .scene files for more info.

A note of caution.
The configfile and the scenefile are read as parameters and the last parameter with a given name will take precedence. Parameters in the scenfile take precedence over parameters in the configfile. There are exceptions to this, some parameters are treated as arrays (eg. lightsources).

configfile

The configfile is a xml-file and will be created the first time you start StyrofoamIFS if not present already. It contains the options selected in the StyrofoamIFS dialog. The parameters marked in reddish bold is used by the raytracer.

<?xml version="1.0" encoding="utf-8"?>
<param xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 <parallell_processes>4</parallell_processes>
 <cache_splits>16</cache_splits>
<cl_iter>0</cl_iter>

 <movie_start_anim>0</movie_start_anim>
 <movie_stop_anim>1</movie_stop_anim>
 <movie_anim_speed>1</movie_anim_speed>
<cuda>1</cuda>

<opencl_platform>0</opencl_platform>

<opencl_device>0</opencl_device>

<pic_width>1024</pic_width>

<pic_height>1024</pic_height>

<pic_width_offset>0</pic_width_offset>

<pic_height_offset>0</pic_height_offset>

<pic_width_total>1024</pic_width_total>

<pic_height_total>1024</pic_height_total>

 <timeformat>HH:mm:ss</timeformat>
 <cl_build_options>-cl-mad-enable</cl_build_options>
 <ifs_file>tetra_rotate2.ifs</ifs_file>
 <scene_file>escapetime2.scene</scene_file>
 <notepad>C:\Program Files\Notepad++\notepad++.exe</notepad>
 <test>0</test>
</param>

cl_iter is the number of points in the point-cloud that will be considered during each call to opencl/cuda. Set to 0 to consider all points in the cache-file during each call. This was an attempt to not get Windows to reset the graphics-drivers when it hasn't responded in time (2 seconds by default). It turns out that even if I set this value quite low, during a long run, something not related to this program will happen and get included in those 2 seconds and still cause a reset and subsequent crash.

cuda Set to 0 to use opencl, 1 to use cuda.

opencl_platform is the platform set in the dialog. Only used for OpenCL.

opencl_device is the device set in the dialog. Only used for OpenCL.

pic_width is the width of the output image set from the dialog.

pic_height is the height of the output image set from the dialog.

pic_width_offset is the offset of the current subframe, use when rendering large images that needs to be split up. Set to 0 if not using subframes.

pic_height_offset is the offset of the current subframe, use when rendering large images that needs to be split up. Set to 0 if not using subframes.

pic_width_total is the total width of the final image, use when rendering large images that needs to be split up. Set to same value as pic_width if not using subframes.

pic_height_total is the total height of the final image, use when rendering large images that needs to be split up. Set to same value as pic_height if not using subframes.

cachelistfile

This is a text-file that contains the list of point-cloud cache files that should be rendered. It is possible to manually edit this file and then use the Retrace-button from the main dialog. This lets you for example copy the result of one run to a separate cache-folder, make a new run, and then add the paths to the previous files here and render both results in the same scene.

C:\Users\Per\Documents\StyrofoamIFS\cache\_ifs_cache_0.tmp;
C:\Users\Per\Documents\StyrofoamIFS\cache\_ifs_cache_1.tmp;
C:\Users\Per\Documents\StyrofoamIFS\cache\_ifs_cache_2.tmp;
C:\Users\Per\Documents\StyrofoamIFS\cache\_ifs_cache_3.tmp;
C:\Users\Per\Documents\StyrofoamIFS\cache\_ifs_cache_4.tmp;
C:\Users\Per\Documents\StyrofoamIFS\cache\_ifs_cache_5.tmp;
C:\Users\Per\Documents\StyrofoamIFS\cache\_ifs_cache_6.tmp;
C:\Users\Per\Documents\StyrofoamIFS\cache\_ifs_cache_7.tmp;

point-cloud cache files

The cache-files are binary files normally created by create_ifs_cache_cpp.exe and each file consists of a stand-alone container of a point-cloud. Each file is divided into five sections. The header is required, the other sections can be of size 0. The spheres are divided in groups of nearby points contained in bounding spheres. All spheres must be contained in a corresponding bounding sphere in the bounding_spheres section.

Half-floats are used in the bounding_spehres, spheres and colors sections to minimize memory usage (the cache-files are loaded to graphics memory). Half-floats is supported inherently in OpenCL and Cuda and I use the implementation in glm to read and write half-floats. To store bounding sphere radiuses there is a rewritten variant used that rounds the half-float values up so that no spheres contained inside gets missed.

header
bounding_spheres
bounding_ref
spheres
colors

header

The header is described in bank_header.h in the shared_cpp project in the code.
struct bank_header {
 unsigned int bcount;
 unsigned int count;
 glm::vec4 bounding_sphere;
 glm::vec4 color_reflection;
 unsigned int mask;
 float sphere_size;
}
glm::vec4 This type is a vector of four float32s, named x,y,z and w.
unsigned int 32-bit unsigned integer.
float 32-bit float.
bcount This is the number of bounding spheres and determine the size of the bounding_spheres and the bounding_ref sections.
count This is the number of spheres and determine the size of the spheres section and if color-data is present the colors section.
bounding_sphere x,y and z contains the center position and w contains the radius of a sphere that bounds all points in this cache-file.
color_reflection If all points in the point-cloud has the same color then x,y and z is used as the red, green and blue values of every point. If all points in the point-cloud has the same reflection-value w contains this value. The COLOR-bit in the mask below controls if the colors section should be used or the color-value here. The REFLECTION-bit in the mask below controls if the colors section should be used or the reflection-value here. All values are in the range [0,1]
mask This is a bit-field that tells what the spheres and colors sections contains. enum { REFLECTION = 1, SPHERE_SIZE = 2, COLOR = 4 }; bit 0, REFLECTION: If this bit is set then the colors-section contains reflection-values.
bit 1, SPHERE_SIZE: If this bit is set then the spheres-section contains a radius value for each sphere.
bit 2, COLOR: If this bit is set then the colors-section contains color-values.
sphere_size If all points in the point-cloud has the same size then this value is used as size for all points in the point-cloud. The SPHERE_SIZE-bit in the mask above controls if the spheres section includes sphere-radiuses or this value should be used.

bounding_spheres

Array of bcount bounding spheres. Bcount is found in the header. Each bounding sphere is stored as center point and size in 4 half-floats.
xyzradius

bounding_ref

Array of bcount references. The references are 32-bit unsigned integers (unsigned int). Bcount is found in the header. The values represent indexes to the spheres and colors sections and tell which bounding spheres belong to which sphere. The value indicates the first index of the following bounding sphere. For example, if the first values are 4,12 and 20 in the bounding_ref array means that spheres 0-3 belong to the first bounding sphere, that spheres 4-11 belong to the second bounding sphere and that sphere 12-19 belong to the third bounding sphere.

spheres

Array of count spheres. The SPHERE_SIZE bit and count are found in the header. Each sphere is stored as an offset from the bounding sphere center and optionally a size in 3 or 4 half-floats.
If the SPHERE_SIZE bit is 0
offset xoffset yoffset z

If the SPHERE_SIZE bit is 1
offset xoffset yoffset zradius

colors

Array of count colors. Each value contains the color-value and the reflection-value of the sphere at the same index. Values are stored as 0, 1, 3 or 4 half-floats. REFLECTION and COLOR bits and count are found in the header. Note that if REFLECTION and COLOR is 0 (the first case below) then there is no colors section at all.
If the REFLECTION bit is 0 and the COLOR bit is 0
The colors section is not used.

If the REFLECTION bit is 1 and the COLOR bit is 0
reflection-value

If the REFLECTION bit is 0 and the COLOR bit is 1
redgreenblue

If the REFLECTION bit is 1 and the COLOR bit is 1
redgreenbluereflection-value