How To Use The JSON Interface

A brief overview on using the JSON scene definition format.

Broken down into sections, as they can be found in the default scene.json At this time, you should provide all the configuration options in the JSON until I've implemented sane defaults to override instead.

version

Leave at 1.0. Just futureproofing in case I add features later that are not backwards-compatible.

renderer

• threadCount - Amount of threads to render with. 0 defaults to system logical core count.
• sampleCount - Amount of samples to render. More samples -> Smoother image with less noise.
• antialiasing - Enable or disable antialiasing. (Reduces jagged edges)
• newRenderer - Enable or disable the new recursive (but buggy!) rendering algorithm.
• tileWidth - Width of the tiles the image is quantised into.
• tileHeight - Height of the tiles the image is quantised into.
• tileOrder - Order the tiles are rendered in. Doesn't affect render time, mostly just helps with debugging when you can decide roughly which part of the image is rendered first. Available options are: normal, random, topToBottom, fromMiddle, toMiddle.

display

• isFullscreen - Enable or disable fullscreen mode for SDL render preview window
• isBorderless - Enable or disable window borders for SDL render preview window.
• windowScale - Adjust the size of the SDL render preview window. This is a multiplier from 0.0->1.0 (i.e. 0.5 is one half the size of 1.0)

camera

• FOV - Camera field of vision. The smaller the value, the narrower the field of vision.
• aperture - Aperture of the camera. So far there is no 'focal plane', so everything just sort of becomes blurry if this is above 0.0
• transforms - Array of transforms for the camera. (For now, make sure the translate transform is first in this list!)

scene

• filePath - The file path in which the output image will be written to, relative to the working directory (Usually the project root)
• fileName - Name prefix of the output image file
• count - The number postfix of the image file
• width - Width of the image in pixels
• height - Height of the image in pixels
• fileType - File type of the output image file. Available options are: png and bmp (Stick to PNG as it's losslessly compressed)
• ambientColor - This color to every pixel in the final image where the ray didn't hit anything within 20k distance units. It's a dark turquoise by default.
• contrast - Currently unused
• bounces - The amount of times a ray can bounce in the scene. This determines reflection depth.
• areaLights - Enable or disable approximated area lights (And thus, soft shadows)
• inputFilePath - The file path from which the source files (OBJ meshes, MTL files) are to be retrieved from, relative to the working directory (Usually the project root)
• lights - Array of lights to be placed in the scene
• spheres - Array of spheres to be placed in the scene
• OBJs - Array of 3D models to be placed in the scene

Object types and their usage

transform

Transforms are used to move, rotate and scale most objects, excluding (for now) spheres and lights.

Transform parameters:

• type - Transform type. These are listed below, including the required parameters for each.
• x - X displacement/scale factor, if needed
• y - Y displacement/scale factor, if needed
• z - Z displacement/scale factor, if needed
• degrees - degrees to rotate an object by, if needed
• scale - scale factor to uniformly scale an object by, if needed

Transform types and required parameters for each

• rotateX - Rotate the object in the X axis by N degrees

Required parameters: degrees

• rotateY - Rotate the object in the Y axis by N degrees

Required parameters: degrees

• rotateZ - Rotate the object in the Z axis by N degrees

Required parameters: degrees

• translate - Translate the object (move it around) in 3D Space by +/- X, Y, Z

Required parameters: X, Y, Z

• scale - Scale the object by a +/- factor in the X, Y, Z axis

Required parameters: X, Y, Z

• scaleUniform - Scale an object uniformly on all axis by a scaling factor

Required parameters: scale

color

Colors are only used to set the ambient color, and sphere colors.

color parameters:

• r - Red value, from 0.0 to 1.0
• g - Green value, from 0.0 to 1.0
• b - Blue value, from 0.0 to 1.0
• a - (Optional) Alpha transparency value, from 0.0 to 1.0

coordinate

Coordinates are only used to set the positions for objects that don't yet use transforms.

coordinate parameters:

• x - X coordinate in space
• y - Y coordinate in space
• z - Z coordinate in space

light

Lights are fairly simple for now. It's actually just a point light, and we calculate a random distribution within the given radius to approximate area lights.

light parameters:

• pos - coordinate object, the location of this light.
• radius - radius (size) of this light.
• color - color object, the color of this light.
• intensity - The brightness of this light.

sphere

Spheres are again fairly simple, just a point and a radius in space, with color and reflectivity.

sphere parameters:

• pos - coordinate object, the location of this sphere.
• color - color object, the color of this sphere
• reflectivity - The reflectivity of this sphere, from 0.0 -> 1.0
• radius - The size of this sphere

OBJ

OBJs are the 3D models that you can export from popular programs like Blender.

OBJ parameters:

• fileName - The file name to load from. If not found, will be skipped (with error message)
• transforms - Array of transform objects to apply to this mesh. (For now please make sure translate transforms are last in this array! Otherwise you get weird behavior)