NeoX HLSL DialectNeoX HLSL 方言

Language Overview语言概览

NeoX shaders are written in a custom HLSL dialect that extends standard HLSL with engine-specific types, conventions, and cross-platform macros. The same source compiles to D3D11, OpenGL ES 3.0, and Metal via preprocessing.

NeoX 着色器使用自定义 HLSL 方言编写，在标准 HLSL 基础上扩展了引擎特定类型、约定和跨平台宏。同一份源码通过预处理编译为 D3D11、OpenGL ES 3.0 和 Metal。

Core Data Types — The Four Struct Interface核心数据类型 — 四大结构体接口

All NeoX shaders communicate through four fundamental structs. This is the engine's "shader contract":

所有 NeoX 着色器通过四个基础结构体通信。这是引擎的"Shader 契约"：

// Engine-provided structs (defined by pipeline)

struct Fragment {
  float4 position;           // SV_Position (clip space)
  float3 position_world;     // world-space position
  float4 position_screen;    // screen-space position
  float2 texcoord0;          // UV channel 0
  float3 normal_world;       // interpolated normal
  float3 tangent_world;      // interpolated tangent
  float3 binormal_world;     // interpolated binormal
};

struct Material {
  float3 albedo;             // base color (linear)
  float3 normal;             // world normal (after normal map)
  float  roughness;          // [0..1]
  float  metalness;          // [0..1]
  float  specular;           // specular intensity
  float  occlusion;          // ambient occlusion
  float3 emissive;           // self-illumination
  float3 tangent;            // for anisotropy / hair
  float4 sh;                 // spherical harmonics data
  uint   shading_model;      // enum: Isotropy, Skin, Hair...
  float  two_sided_sign;     // face direction sign
};

struct View {
  float3 position;           // camera world position
  float3 direction;          // normalized view direction
  float  distance;           // camera-to-pixel distance
};

struct Light {
  float3 direction;          // light direction (normalized)
  float3 color;              // light color * intensity
  float  attenuation;        // distance attenuation
};

Entry Points — vs_main / ps_main入口函数 — vs_main / ps_main

Every NeoX shader has two mandatory entry points. The vertex shader transforms geometry; the pixel shader evaluates materials and lighting:

每个 NeoX 着色器有两个必需入口点。顶点着色器变换几何体；像素着色器计算材质和光照：

// Vertex Shader (from forward_shading.hlsl)
Fragment vs_main(Vertex input) {
  Fragment frag = (Fragment)0;
  CommonVertex vert = TransformCommonVertex(input, vert_inter);
  
  ApplyVertexOffsetLocal(vert, vert.position);
  #if GPU_SKIN_ENABLE
    DoSkin(vert.blendWeights, vert.blendIndices, ...);
  #endif
  
  float4 world_position = Transform(vert.world_mat, vert.position);
  SetupFragment(vert, vert_inter, mtl_vtx_params, world_position, frag);
  return frag;
}

// Pixel Shader
float4 ps_main(Fragment input, bool is_front_face : SV_IsFrontFace) : SV_Target0 {
  Material mtl = (Material)0;
  View v = (View)0;
  v.position = CameraPosition;
  v.direction = normalize(input.position_world - CameraPosition);
  
  RawData raw_data = GetRawData(input);   // sample textures
  SetupMaterial(input, raw_data, mtl);    // fill Material struct
  
  // ... lighting calculation ...
  return final_color;
}

Cross-Platform Macros跨平台宏

NeoX targets three graphics APIs from a single source. Platform differences are resolved via these macros:

NeoX 从单一源码目标化三种图形 API。平台差异通过以下宏解决：

// Platform-specific depth handling example
#ifdef NEOX_GLSL
  float depth = -(2 * output.z - 1);      // GL: [-1,1] range
#else
  float depth = 1 - output.z;              // D3D: [0,1] range
#endif

// Screen UV Y-flip for D3D
#ifndef NEOX_GLSL
  input.position_screen.y = 1 - input.position_screen.y;
#endif

Include Hierarchy包含层级

NeoX shaders follow a strict include hierarchy. Understanding this tree is essential for navigation:

NeoX 着色器遵循严格的包含层级。理解这棵树对导航至关重要：

Utility Library — function.hlsl (977 lines)工具函数库 — function.hlsl (977 行)

The function.hlsl library provides optimized math primitives used throughout the entire shader codebase. It grew from 782 to 977 lines in the new engine:

function.hlsl 库提供整个着色器代码库中使用的优化数学原语。新引擎中从 782 行增长到 977 行：