Axmol v3 Moves to an HLSL-First Shader Workflow

[halx99]

Axmol v3 is receiving a foundational upgrade to its cross-platform rendering workflow. The engine shader library has moved from the legacy GLSL-source pipeline to an HLSL-first model. Developers can now maintain one HLSL source and use the new Axmol-specific axslcc 3.99 compiler to produce target code and runtime reflection for D3D11, D3D12, Vulkan, Metal, OpenGL, and OpenGL ES.

This work goes far beyond translating .vert and .frag files into .hlsl. It redesigns the contract between shader compilation, resource reflection, vertex inputs, samplers, and every RHI backend. The result is a more consistent cross-platform model and a cleaner foundation for future rendering work.

One HLSL Source Across All RHIs

The new CMake shader pipeline selects compiler targets from the RHI backends enabled by the project. Vertex, pixel, and compute shaders use the _vs.hlsl, _fs.hlsl/_ps.hlsl, and _cs.hlsl suffixes, and axslcc packages the required backend variants in one build workflow. The build system also supports shader variants with different preprocessor definitions generated from the same source.

Axmol's built-in shaders, 3D renderer, VR support, ImGui, Live2D, Spine, the Box2D Testbed, and cpp-tests have all been migrated. The old GLSL conversion scripts and generated shader-info path are retired as part of the change.

Vertex Inputs Are Matched by Semantics

The previous workflow commonly treated variable names such as a_position and a_texCoord as the binding contract. The HLSL-first workflow instead matches vertex data by HLSL semantic name and index:

struct VSInput
{
    float3 position : POSITION;
    float2 uv       : TEXCOORD0;
    float4 color    : COLOR0;
};

The variables may be named position, pos, or anything else. The stable contract is POSITION0, TEXCOORD0, and COLOR0. In addition to Axmol's built-in semantics, the runtime supports custom semantics for specialized render paths and instance data.

A Unified Sampler Model

Sampler handling is another major part of the redesign. base.hlsli exposes 22 stable built-in presets, covering common combinations such as LinearClamp, PointWrap, AnisoClamp, and comparison samplers:

#include "base.hlsli"

Texture2D u_tex0;

float4 main(float2 uv : TEXCOORD0) : SV_Target0
{
    return u_tex0.Sample(LinearClamp, uv);
}

When a preset is not enough, a shader may declare a named custom SamplerState. Its state is registered through SamplerRegistry before the Program is created. Reflection stores stable logical bindings, and each backend translates those bindings into D3D sampler slots, D3D12 descriptors, Vulkan descriptor sets, Metal samplers, or GL/ES combined samplers.

Program validation now rejects unresolved custom samplers and failed shader modules before those errors reach the draw path.

A New Reflection and Resource-Binding Contract

The axslcc 3.99 shader package and reflection ABI have been redesigned for the Axmol RHI. Runtime reflection now carries:

• vertex semantic names, indices, and backend locations;
• final bindings for textures, samplers, uniform buffers, and storage resources;
• an explicit distinction between built-in sampler presets and Program-local custom samplers;
• the metadata needed to identify textual target code and native bytecode.

Shader authors do not write register(...) annotations. Resources are declared normally, the compiler assigns deterministic logical bindings, and the RHI translates them for the active backend. D3D11, D3D12, Vulkan, Metal, and OpenGL/ES have all been updated for this model, including separate Vulkan image/sampler descriptor handling and revised D3D12 descriptor-heap allocation.

Migration Notes

New shaders should normally include base.hlsli, use HLSL semantics, and let axslcc assign resource bindings. Uniform and texture names remain part of the C++ lookup contract and therefore should not be renamed casually.

OpenGL and OpenGL ES ultimately use combined samplers. To preserve consistent behavior across all backends, a shader should not sample the same texture with multiple sampler states. Use separate texture bindings when different sampling behavior is required.

UV Y flipping should not be added mechanically just because a shader moved from GLSL to HLSL. 1.0 - uv.y is a data-space conversion, while AX_Y_UP() is a backend-dependent coordinate conversion; choose according to what the input coordinates represent.

For complete specifications, migration guidance, and frequently asked questions, see:

• HLSL Shader Specification
• HLSL FAQ
• Shaders in Axmol 3

Validation

The migrated HLSL shader set has passed the complete RHI cpp-tests validation. Before merge, the dependency will be updated from the release candidate to the final axslcc 3.99.0 release.

HLSL-first gives Axmol a single, explicit contract spanning shader sources, compiler reflection, and every graphics backend. It reduces duplicated shader code and backend-specific exceptions while providing a stronger foundation for the next stage of Axmol v3 rendering development.