Code Device

This feature was introduced in the “Hurricane Ridge” release

The Code device lets you write custom devices for World Machine. These device plugins use GPU compute and can be shared with other users safely, due to the sandboxed execution model.

Overview

Your Code device contains custom programming that you create as follows:

1. A script controlling the execution of the device, written in Lua.
2. Zero or more compute kernels for executing code on the GPU.

When you create a new Code device and open it for editing, you will see the Code Editor view:

• The tabs across the top allow you to access the Host code (scripting language) and the Compute code (OpenCL or equivelent).
• The tabs at the bottom show you any reported errors during compilation or execution of your device in the first tab, and any host script output (such as that created by the print() function) in the second tab.
• The right side drawers allow you to modify the configuration of your custom device, including adding ports, parameters, and more.
• The “apply changes” button commits any changes you’ve written in your code and rebuilds the device.

Languages

Your device is written in both a host language and a compute language.

• The host language is a slow scripting language executed on the CPU. Your host script acts to orchestrate the execution of your device, but should perform no major calculations itself.
• The compute language is a fast, data-parallel language executed on the GPU. This is used for code that manipulates large amounts of data, such as the entire contents of a heightfield or image.

Host Language

Currently Lua is the allowed host script language. Other languages may be supported in the future.

The Lua environment is by default heavily sandboxed. Other than core language function, only the standard math library is enabled. Your script will interact with World Machine via the World Machine library (exposed as ‘wm’).

This looks much like:

-- Create an empty memory buffer
wm.createBuffer()

-- Get a parameter
local myFloat = wm.parm("parm0")

-- Output to port 0
wm.output(bufResult, 0)

See the World Machine Lua API Reference for complete details of how to interact with World Machine.

Compute Language

Currently OpenCL is the compute language. Other languages may be supported in the future. OpenCL 1.2 is the minimum version required. Compute kernels are compiled by your GPU drivers and run on the GPU.

Any valid compute kernel can be run within World Machine.

See the Language References section for links for general information on writing compute kernels in OpenCL C.

Configuration

A number of configuration options are available for your device:

• Identity is the most important thing to assign. When you click the Assign button, you can name your device. Naming the device embeds a hidden globally unique class identifier. Devices that have the same GUID will be considered the “same” in the eyes of World Machine, in much the same way that different Basic Perlin devices are the same. This enables you to copy/paste settings between those devices, etc. If you change the Identity of the device, it will no longer be considered the same… do so carefully.
• The Family of the device controls its appearance, and where it gets sorted within the various menus and toolbars in World Machine
• The Summary should be a brief description of what the device does
• The Description can be more in depth. It is displayed when the user clicks a help icon.

Parameters, inputs, and outputs are created the same as for Macros. To retrieve your parameters from the script, refer to it by the ID you’ve given it – this can be the automatically assigned one, or a custom one. For example:

Limitations

There are a number of limitations right now in the Code device.

• The scripting bindings to World Machine are still under construction.
• Currently only supports heightfield and bitmap datatypes for compute.
• You can only provide a build script. No other control of the device is possible.
• There is no access to built-in functions, such as rescaling a packet. This would be very useful.
• Only Lua and OpenCL are supported

Some of these limitations will be improved over time.

Resources

World Machine

• World Machine Lua API

Language References

• OpenCL API Reference Sheet
• OpenCL Kernel Language Reference

• Lua – Getting Started
• Lua Reference Guide

CPU Drivers

The default GPU backend is OpenCL. Although the Code device is intended to be GPU accelerated, you may wish to use the Intel OpenCL CPU driver to run code on your processor.

• Intel OpenCL CPU Drivers

The Intel driver has been tested and works well. (Yes, you can also use it with AMD-based systems).

For many common scenarios within World Machine, the OpenCL performance running on the CPU is competitive with the GPU.