clay/bindings/jai/README.md

Jai Language Bindings

This directory contains bindings for the Jai programming language, as well as an example implementation of the Clay demo from the video in Jai.

If you haven't taken a look at the full documentation for clay, it's recommended that you take a look there first to familiarise yourself with the general concepts. This README is abbreviated and applies to using clay in Jai specifically.

The most notable difference between the C API and the Jai bindings is the use of for statements to create the scope for declaring child elements. This is done using some for_expansion magic. When using the equivalent of the Element Macros:

// C form of element macros
// Parent element with 8px of padding
CLAY(CLAY_LAYOUT({ .padding = 8 })) {
    // Child element 1
    CLAY_TEXT(CLAY_STRING("Hello World"), CLAY_TEXT_CONFIG({ .fontSize = 16 }));
    // Child element 2 with red background
    CLAY(CLAY_RECTANGLE({ .color = COLOR_RED })) {
        // etc
    }
}

// Jai form of element macros
// Parent element with 8px of padding
for Clay.Element(Clay.Layout(.{padding = 8})) {
	// Child element 1
	Clay.Text("Hello World", Clay.TextConfig(.{fontSize = 16}));
	// Child element 2 with red background
	for Clay.Element(Clay.Rectangle(.{color = COLOR_RED})) {
		// etc
	}
}

Warning

For now, the Jai and Odin bindings are missing the OnHover() and Hovered() functions. You can you PointerOver instead, an example of that is in examples/introducing_clay_video_demo.

Quick Start

1. Download the clay-jai directory and copy it into your modules folder.

Clay :: #import "clay-jai";

1. Ask clay for how much static memory it needs using Clay.MinMemorySize(), create an Arena for it to use with Clay.CreateArenaWithCapacityAndMemory(), and initialize it with Clay.Initialize().

clay_required_memory := Clay.MinMemorySize();
memory := alloc(clay_required_memory);
clay_memory := Clay.CreateArenaWithCapacityAndMemory(clay_required_memory, memory);
Clay.Initialize(
	clay_memory, 
	Clay.Dimensions.{cast(float, GetScreenWidth()), cast(float, GetScreenHeight())},
	.{handle_clay_errors, 0}
);

3. Provide a measure_text(text, config) proc marked with #c_call with Clay.SetMeasureTextFunction(function) so that clay can measure and wrap text.

// Example measure text function
measure_text :: (text: *Clay.String, config: *Clay.TextElementConfig) -> Clay.Dimensions #c_call {
}

// Tell clay how to measure text
Clay.SetMeasureTextFunction(measure_text)

4. Optional - Call Clay.SetPointerPosition(pointerPosition) if you want to use mouse interactions.

// Update internal pointer position for handling mouseover / click / touch events
Clay.SetPointerPosition(.{ mousePositionX, mousePositionY })

5. Call Clay.BeginLayout(screenWidth, screenHeight) and declare your layout using the provided macros.

// An example function to begin the "root" of your layout tree
CreateLayout :: () -> Clay.RenderCommandArray {
	Clay.BeginLayout(windowWidth, windowHeight);

	for Clay.Element(
		Clay.ID("OuterContainer"),
		Clay.Layout(.{
			sizing = .{Clay.SizingGrow(), Clay.SizingGrow()},
			padding = .{16, 16},
			childGap = 16
		}),
		Clay.Rectangle(.{color = .{250, 250, 255, 255}}),
	) {
		// ...
	}
}

1. Call Clay.EndLayout() and process the resulting Clay.RenderCommandArray in your choice of renderer.

render_commands: Clay.RenderCommandArray = Clay.EndLayout();

for 0..render_commands.length - 1 {
	render_command := Clay.RenderCommandArray_Get(*render_commands, cast(s32) it);

	if #complete render_command.commandType == {
	case .RECTANGLE;
		DrawRectangle(render_command.boundingBox, render_command.config.rectangleElementConfig.color)
	// ... Implement handling of other command types
	}
}

Please see the full C documentation for clay for API details. All public C functions and Macros have Jai binding equivalents, generally of the form CLAY_RECTANGLE (C) -> Clay.Rectangle (Jai)