Skip to content

CrossGL Translator 🌟

The Translator is a cornerstone of our platform, expertly bridging the gap between CrossGL shader code and leading graphics APIs like DirectX, Metal, and Vulkan. Whether you're a seasoned developer or just starting out, this tool empowers you to effortlessly translate and deploy shaders across multiple platforms, expanding the versatility and impact of your graphics projects.

Getting Started

To begin using CrossGL, you\'ll need to install its translation library. This is easily done using pip.

Installation

Run the following command to install CrossGL\'s translation library:

pip install crosstl

Once installed, you\'re ready to start translating shaders with CrossGL!

  • Introduction to CrossGL Translator:
    • A tool that translates CrossGL shader code into different graphics API languages like DirectX, Metal, and Vulkan.
    • Designed to streamline shader development across multiple platforms.
  • Core Features:
    • Streamlined Shader Conversion: Translates shaders directly into crosstl languages or IR, bypassing unnecessary steps.
    • Consistent Multi-Platform Support: Unified AST supporting multiple graphics APIs.
    • Tailored Code Optimization: Optimized code for each target backend ensuring peak performance.

Key Features💡

  • Streamlined Shader Conversion: Our system translates shaders directly into crosstl languages or intermediate representations (IR), bypassing unnecessary steps. This approach simplifies the process for developers, ensuring efficiency and ease of use.
  • Consistent Multi-Platform Support: With a unified Abstract Syntax Tree (AST), our platform supports various graphics APIs, enabling developers to write shaders once and deploy them across multiple platforms seamlessly.
  • Tailored Code Optimization: The code generated by our system is highly optimized for each target backend, ensuring that shaders perform at their best. Whether you're focusing on speed or resource efficiency, our platform delivers code that's finely tuned for optimal performance.

Quick Guide to Translator Structure

Translator is designed to translate CrossGL shader code into different graphics API languages (e.g., HLSL, Metal, OpenGL). The process involves several key steps, from lexing the input code to generating the final output. Below is a quick guide to the structure and workflow of Translator:

  1. Lexical Analysis (Lexer)

    Purpose:

    • Breaks down the input CrossGL shader code into a series of tokens (lexical units).

    Process:

    • The lexer reads the shader code and identifies keywords, operators, identifiers, literals, etc.

    Example tokens: SHADER, INPUT, OUTPUT, VOID, MAIN, IDENTIFIER, NUMBER, etc.

    Output:

    • A list of tokens that represent the structure of the shader code.

  2. Syntax Analysis (Parser)

    Purpose:

    • Analyzes the sequence of tokens and builds a syntactic structure known as the Abstract Syntax Tree (AST).

    Process:

    • The parser checks the token sequence for grammatical correctness based on the defined grammar of CrossGL.
    • Constructs the AST nodes such as [ShaderNode]{.title-ref}, [FunctionNode]{.title-ref}, [VariableNode]{.title-ref}, etc.

    Output:

    • An AST that represents the hierarchical structure of the shader code.

  3. Abstract Syntax Tree (AST) Construction

    Purpose:

    • Represents the logical structure of the shader code in a tree format.

    Process:

    • AST nodes are created during parsing, each representing a syntactical element of the shader (e.g., functions, variables, operations).
    • Nodes include details about data types, operations, and relationships between different code elements.

    Output:

    • A complete AST that can be further analyzed or transformed.

  4. Optimization (AST Optimization)

    Purpose:

    • Refines and optimizes the AST for better performance and efficiency.

    Process:

    • Performs optimizations such as constant folding, dead code elimination, and loop unrolling.
    • Simplifies expressions and optimizes data structures within the AST.

    Output:

    • An optimized AST ready for code generation.

  5. Code Generation (CodeGen)

    Purpose:

    • Translates the optimized AST into the target platform-specific shader code (HLSL, Metal, OpenGL, etc.).

    Process:

    • The code generation module traverses the AST and converts it into the corresponding language's syntax.
    • Handles the conversion of functions, variables, and other shader constructs into the target language.

    Output:

    • Platform-specific shader code that is ready for use in the target graphics API.

Workflow Summary

  1. Lexical Analysis: Input shader code is tokenized.
  2. Syntax Analysis: Tokens are parsed into an AST.
  3. AST Construction: The logical structure of the shader is represented.
  4. Optimization: The AST is refined for performance.
  5. Code Generation: Optimized AST is converted into the target shader language.

This structured approach ensures that the shader code is accurately translated and optimized for different platforms, maintaining both performance and compatibility.

How It Works 🛠️

The Translator processes CrossGL shader code through several key stages, ensuring a smooth and efficient transformation :

| 1.Parsing 🌲 : | The first stage in the CrossGL shader pipeline is the Parsing phase, where the shader code is meticulously analyzed and broken down into its constituent parts. This process begins with a lexical analysis, where the code is tokenized into manageable pieces such as keywords, identifiers, operators, and literals. These tokens are then passed through a syntactical analysis to construct the Abstract Syntax Tree (AST). The AST is a hierarchical, tree-like structure that represents the logical flow and structure of the shader code. Each node in the AST corresponds to a construct in the shader, such as variable declarations, function definitions, and control flow statements. By converting the code into an AST, CrossGL allows for a clear and organized representation of the shader's logic, making it easier to perform further transformations, optimizations, and analyses. This structured representation serves as the foundation for all subsequent stages in the shader compilation process.

| 2.Intermediate Representation 🔗 : | After the AST is generated, the next step is to transform it into an Intermediate Representation (IR). The IR acts as an abstraction layer between the high-level CrossGL shader code and the low-level machine code that will eventually run on the hardware. This representation is designed to be both flexible and portable, allowing it to adapt to the specific needs of various graphics APIs like DirectX, Metal, or Vulkan. The IR retains the logical structure and intent of the original code while abstracting away platform-specific details, making it easier to perform optimizations and transformations that are crucial for efficient execution. Additionally, the IR enables the CrossGL system to apply uniform optimizations across different platforms, ensuring that the shader code remains performant regardless of the target environment. The IR serves as a critical stepping stone, bridging the gap between the high-level constructs in the shader code and the low-level instructions required by the graphics hardware.

| 3.Code Generation ⚙️ : | With the IR in place, the process moves on to the Code Generation stage. Here, the IR is translated into the target backend code specific to the chosen graphics API, whether it's DirectX for Windows, Metal for macOS, or Vulkan for cross-platform compatibility. This stage involves mapping the abstract constructs in the IR to the concrete syntax and semantics of the target API. The translation process is designed to preserve the original intent and functionality of the CrossGL shader code while ensuring that it adheres to the conventions and requirements of the target platform. During this phase, the code generator also handles the integration of platform-specific features and optimizations, such as memory management, thread synchronization, and resource binding. The result is a backend-specific shader code that is ready to be compiled and executed on the target hardware, ensuring that the shader behaves consistently across different environments.

| 4.Optimization ⚡ : | Once the target backend code is generated, the Optimization phase begins. This stage is crucial for enhancing the performance of the shader, ensuring that it runs efficiently on the intended platform. Various optimization passes are applied to the code, each tailored to address specific aspects of shader execution. These optimizations may include reducing the number of instructions, minimizing resource usage (such as registers and memory), and improving data locality to enhance execution speed. Additionally, platform-specific optimizations are applied to take full advantage of the hardware capabilities, such as parallel processing on GPUs, efficient use of shader cores, and minimizing latency in data access. The goal of this stage is to produce a highly optimized shader that not only functions correctly but also delivers the best possible performance on the target platform.

| 5.Final Output 🎯 : | After all the processing and optimization stages are complete, the Final Output is produced. This is the fully optimized shader code, ready for integration into your graphics application. Whether the shader is destined for a game engine, a rendering pipeline, or a specialized graphics tool, the final output is designed to meet the highest standards of performance, compatibility, and reliability. The shader is now in a format that can be directly compiled and executed by the target platform, ensuring smooth deployment and execution. This final stage marks the culmination of the CrossGL shader pipeline, where all the intricate processes of parsing, intermediate representation, code generation, and optimization come together to produce a shader that is not only functional but also optimized for peak performance across different platforms.

Cross-Platform Bridging 🌉: From Platform-Specific to CrossGL and Back

CrossGL is a versatile tool that goes beyond simple translation from a universal language to platform-specific shaders. It's bidirectional translation capability allows developers to seamlessly convert shaders between platform-specific languages like HLSL, MSL, and GLSL to CrossGL and then back again. This flexibility ensures that your shaders can be consistently optimized, maintained, and deployed across multiple platforms with ease.

Two-Way Conversion 🔄

With CrossGL, you can not only convert CrossGL code into HLSL for DirectX, MSL for Metal, or GLSL for OpenGL, but you can also take existing shaders written in these platform-specific languages and convert them back into the CrossGL format. This two-way conversion is incredibly powerful for developers who want to: - Standardize shaders across multiple platforms: By converting HLSL, MSL, and GLSL shaders into CrossGL, you can unify your shader code into a single, maintainable format, ensuring consistency and reducing redundancy. - Optimize for multiple platforms: Once shaders are in the CrossGL format, they can be re-translated into any of the supported platform-specific languages, ensuring that they are optimized for the specific needs and performance characteristics of each platform.

Unified Shader Management 🛠️

This bidirectional capability of CrossGL simplifies shader management by allowing you to maintain a single version of your shaders in CrossGL. From this central format, you can easily generate platform-specific shaders for different environments or bring platform-specific shaders into the CrossGL ecosystem for centralized management. This flexibility makes it easier to apply updates, bug fixes, and optimizations across all platforms without having to manually edit each shader individually.

A typical CrossGL shader consists of input, output, and the main function. #### Example :shader.cgl

shader main
{
    vertex
    {
        input vec3 position;
        output vec4 color;

        void main()
        {
            color = vec4(position, 1.0);
        }
    }

    fragment {
        input vec4 color;
        output vec4 fragColor;

        void main()
        {
            fragColor = color;
        }
    }
}

Translate to your desired backend : 🔮

import crosstl

#Translate to Metal
metal_code = crosstl.translate('shader.cgl', backend='metal')

#Translate to DirectX (HLSL)
hlsl_code = crosstl.translate('shader.cgl', backend='directx')

#Translate to OpenGL
opengl_code = crosstl.translate('shader.cgl', backend='opengl')

Converting from HLSL to CrossGL

  1. write your HLSL shader (e.g., shader.hlsl):
struct VS_INPUT {
float3 position : POSITION;
};

struct PS_INPUT {
float4 position : SV_POSITION;
float2 uv : TEXCOORD0;
};

PS_INPUT VSMain(VS_INPUT input) {
PS_INPUT output;
output.position = float4(input.position, 1.0);
output.uv = input.position.xy * 10.0;
return output;
}

float4 PSMain(PS_INPUT input) : SV_TARGET {
return float4(input.uv, 0.0, 1.0);
}
  1. Convert to CrossGL:
import crosstl

crossgl_code = crosstl.translate('shader.hlsl', backend='cgl')
print(crossgl_code)

Converting from Metal to CrossGL

  1. write your Metal shader (e.g., shader.metal):
#include <metal_stdlib>
using namespace metal;

struct VertexInput {
    float3 position [[attribute(0)]];
};

struct VertexOutput {
    float4 position [[position]];
    float2 uv;
};

vertex VertexOutput vertexShader(VertexInput in [[stage_in]]) {
    VertexOutput out;
    out.position = float4(in.position, 1.0);
    out.uv = in.position.xy * 10.0;
    return out;
}

fragment float4 fragmentShader(VertexOutput in [[stage_in]]) {
    return float4(in.uv, 0.0, 1.0);
}
  1. Convert to CrossGL:
import crosstl

crossgl_code = crosstl.translate('shader.metal', backend='cgl')
print(crossgl_code)

Converting from CrossGL to HLSL

  1. write your crossGL shader (e.g., shader.cgl):
shader main {
    vertex {
        input vec3 position;
        output vec4 color;

        void main() {
            color = vec4(position, 1.0);
        }
    }

    fragment {
        input vec4 color;
        output vec4 fragColor;

        void main() {
            fragColor = color;
        }
    }
}
  1. Convert to HLSL:
import crosstl

hlsl_code = crosstl.translate('shader.cgl', backend='hlsl')
print(hlsl_code)

Converting from CrossGL to Metal

  1. write your crossGL shader (e.g., shader.cgl):
shader main {
    vertex {
        input vec3 position;
        output vec4 color;

        void main() {
            color = vec4(position, 1.0);
        }
    }

    fragment {
        input vec4 color;
        output vec4 fragColor;

        void main() {
            fragColor = color;
        }
    }
}
  1. Convert to Metal:
import crosstl

metal_code = crosstl.translate('shader.cgl', backend='metal')
print(metal_code)

These examples will help you get started with CrossGL, enabling smooth translation between different shader languages and seamless integration of existing shaders into your CrossGL workflow. Enjoy your shader coding journey! ☃️✨

Supported Platforms 🚀

DirectX: Designed specifically for Windows-based applications, DirectX provides a robust framework for high-performance graphics and multimedia.

Metal: Optimized for macOS and iOS, Metal delivers efficient and low-overhead graphics performance, tailored to Apple's hardware.

OpenGL: A widely-used, cross-platform API, OpenGL offers broad compatibility and ease of use for developing graphics applications across different platforms, including Windows, macOS, and Linux.