Code Generation Utilities

Utilities for normalizing and matching shader stage qualifiers.

crosstl.translator.codegen.stage_utils.compute_local_size(execution_config=None)

Return a three-component workgroup size from execution metadata.

crosstl.translator.codegen.stage_utils.compute_local_size_value(value)

Return a string representation for a local-size dimension value.

crosstl.translator.codegen.stage_utils.normalize_stage_name(stage)

Normalize a shader stage enum or string into a lowercase name.

crosstl.translator.codegen.stage_utils.should_emit_qualified_function(target_stage, qualifier)

Return whether a qualified function belongs in the target output.

crosstl.translator.codegen.stage_utils.stage_matches(target_stage, stage)

Return whether a stage should be emitted for the target stage.

Helpers for recognizing resource query expressions in CrossGL AST nodes.

class crosstl.translator.codegen.resource_query.ResourceQueryMixin

Bases: object

Helpers for resource query metadata propagation and code generation.

build_dimension_query_helper(helper_name, spec)

Build helper code for a texture/image dimension query.

build_sample_count_query_helper(helper_name)

Build helper code for a sample-count query.

build_texture_query_levels_helper(helper_name, spec)

Build helper code for texture mip-level queries.

collect_resource_query_names(node)

Collect resource names used directly in resource query calls.

collect_resource_query_requirements(node)

Collect global and function-parameter resources needing metadata.

dimension_query_spec(type_name)

Return dimension/mip/sample metadata for a queryable resource type.

ensure_query_prefix_helper()

Ensure shared query helper code has been registered.

generate_dimension_query(func_name, raw_args, args)

Generate a helper call for a dimension query, if supported.

generate_sample_count_query(func_name, raw_args, args)

Generate a helper call for a sample-count query, if supported.

generate_texture_query_levels(raw_args)

Generate a helper call for textureQueryLevels, if supported.

get_parameter_type(param)

Return a parameter type from current or legacy AST shapes.

get_variable_node_type(node)

Return a variable type from current or legacy AST shapes.

is_sampled_resource_type(type_name)

Return whether a resource type is sampler-backed.

needs_query_metadata(name, type_name)

Return whether a resource declaration needs query metadata.

query_array_suffix(type_name)

Return the array suffix for a resource type, if present.

query_collect_functions(root)

Collect function-like nodes from an AST subtree.

query_constructor(return_type, values)

Return a constructor expression for a query result.

query_dimension_expression(dimension, mip_arg)

Return a metadata field expression for one queried dimension.

query_helper_prefix()

Return helper code shared by mip-aware dimension queries.

query_metadata_call_arguments(func_name, raw_args, args)

Expand call arguments with resource metadata arguments.

query_metadata_declaration(name, type_name)

Return a metadata variable declaration when required.

query_metadata_expression(resource_expr)

Return the metadata expression paired with a resource expression.

query_metadata_name(resource_name)

Return the generated metadata variable name for a resource.

query_metadata_parameter(name, type_name)

Return an extra metadata parameter declaration when required.

query_metadata_type(type_name)

Return the metadata type used for a resource type.

query_return_type(dimensions)

Return an integer vector type for a dimension query result.

query_type_name(type_name)

Return a string type name suitable for resource query decisions.

query_walk_nodes(root)

Yield AST nodes recursively while avoiding parent/annotation cycles.

raw_function_call_name(node)

Return a function call name without backend formatting.

require_helper_function(name, body)

Register a helper function body if it has not already been added.

Shared diagnostics mixin for reporting resource translation issues.

class crosstl.translator.codegen.resource_diagnostics.ResourceDiagnosticMixin

Bases: object

Fallback helpers for unsupported resource operations in backends.

coord_component(coord, component)

Format one component access on a coordinate expression.

image_atomic_zero_value(resource_type)

Return a neutral fallback value for image atomic operations.

image_value_type(image_type)

Return the scalar/vector value type loaded from an image resource.

is_multisample_resource_type(type_name)

Return whether a resource type denotes a multisample resource.

is_shadow_resource_type(type_name)

Return whether a resource type denotes a shadow sampler.

multisample_zero_value(func_name, resource_type)

Return a neutral fallback value for unsupported multisample calls.

resource_backend_name()

Return the backend name used in generated diagnostic comments.

resource_base_type(type_name)

Strip array suffixes from a resource type string.

shadow_zero_value(func_name)

Return a neutral fallback value for unsupported shadow operations.

surface_x_offset(coord, value_type)

Format a byte offset expression for surface x coordinates.

unsupported_image_atomic_resource_call(func_name, resource_type, _args)

Return diagnostic code for unsupported image atomic operations.

unsupported_multisample_resource_call(func_name, resource_type, _args)

Return diagnostic code for unsupported multisample operations.

unsupported_resource_query_call(func_name, resource_type, _args)

Return diagnostic code for unsupported resource query operations.

unsupported_sampled_resource_call(func_name, resource_type, _args)

Return diagnostic code for unsupported sampled-resource operations.

unsupported_shadow_resource_call(func_name, resource_type, _args)

Return diagnostic code for unsupported shadow sampler operations.

zero_value_for_type(type_name)

Return a neutral generated expression for a simple type.

Helpers for collecting resource-array size hints from CrossGL AST nodes.

crosstl.translator.codegen.resource_arrays.collect_resource_array_size_hints(*, global_arrays, function_arrays, fixed_global_array_sizes=None, fixed_function_array_sizes=None, functions, walk_nodes, expression_name, literal_int_value, visible_literal_int_constants, function_call_name, initial_size, format_size)

Infer resource-array sizes from literal accesses and call propagation.

crosstl.translator.codegen.resource_arrays.format_array_declarator(mapped_base, name, array_suffix, dynamic_array_as_pointer=True)

Format a typed C-style array declarator for generated code.

crosstl.translator.codegen.resource_arrays.split_array_suffix(array_suffix)

Split a C-style array suffix into dimension strings.

Utilities for lowering vector arithmetic expressions during code generation.

class crosstl.translator.codegen.vector_arithmetic.VectorArithmeticMixin

Bases: object

Helpers for inferring and lowering vector arithmetic expressions.

collect_function_return_types(ast_node)

Collect function return types from global and stage-local functions.

expression_result_type(node)

Infer the best-effort result type for an expression node.

lower_vector_binary_operation(left_node, left_expr, right_node, right_expr, operator)

Lower vector binary arithmetic into a helper call when required.

require_vector_binary_helper(vector_info, operator, operand_shape)

Register and return a helper function for vector binary arithmetic.

resource_call_result_type(func_name, raw_args)

Infer the result type of resource-related intrinsic calls.

vector_scalar_parameter_type(vector_info)

Return the scalar parameter type used by generated vector helpers.

vector_type_for_components(component_type, component_count)

Return a vector type name for a component type/count pair.

vector_type_info(type_name)

Return constructor and component metadata for a vector type.

AST utilities for CrossGL code generators.

class crosstl.translator.codegen.ast_utils.ASTUtils

Bases: object

Utilities for AST processing and type conversion.

static expression_to_string(expr)

Render a simple expression node to a string for declarations.

Return type:

str

static get_function_info(function, backend='generic')

Return normalized metadata for a function declaration.

static get_legacy_compatible_semantic(node)

Return semantic metadata from either legacy or current AST nodes.

Return type:

Optional[str]

static get_legacy_compatible_type(node, backend='generic')

Return a type string for either legacy or current AST nodes.

Return type:

str

static get_member_info(member, backend='generic')

Return normalized metadata for a struct member.

static get_parameter_info(parameter, backend='generic')

Return normalized metadata for a function parameter.

static get_semantic_from_attributes(attributes)

Return the first recognized semantic attribute name.

Return type:

Optional[str]

static get_type_string(type_node, backend='generic')

Convert a TypeNode to a backend-specific string.

Return type:

str

static get_variable_info(variable, backend='generic')

Return normalized metadata for a variable declaration.

static is_legacy_ast_node(node)

Return whether a node uses the older vtype string shape.

Return type:

bool

static safe_get_body_statements(body)

Extract statements from function body, handling both old and new AST.

static safe_get_function_qualifier(function)

Get function qualifier, handling both old and new AST.

Return type:

Optional[str]

Utility functions for array handling in code generators.

This module provides common functions for handling array types, array access, and type detection across different code generators.

crosstl.translator.codegen.array_utils.collect_literal_int_constants(constants)

Collect resolvable integer compile-time constants by name.

Return type:

Dict[str, int]

crosstl.translator.codegen.array_utils.collect_struct_member_types(structs, type_name_string)

Collect raw struct member types for expression type inference.

Return type:

Dict[str, Dict[str, str]]

crosstl.translator.codegen.array_utils.detect_array_element_type(array_type, type_mapping=None)

Detect the element type of an array based on its type string.

Parameters:

• array_type (str) – The array type string

• type_mapping (Dict[str, Any]) – Optional mapping of types to use for lookups

Return type:

str

Returns:

The detected element type string

crosstl.translator.codegen.array_utils.evaluate_literal_int_expression(expr, constants=None)

Evaluate a narrow integer-only AST expression.

This is used for declaration sizing hints where accepting dynamic values would be unsafe. It intentionally supports only literals, unary signs, and basic arithmetic over integer literals. Named constants are resolved only from the explicit constants map supplied by the caller.

Return type:

Optional[int]

crosstl.translator.codegen.array_utils.format_array_type(base_type, size, lang_style='glsl')

Format an array type according to the target language style.

Parameters:

• base_type (str) – The base type of the array (e.g., “float”, “vec3”)

• size (Optional[int]) – The size of the array, or None for dynamic arrays

• lang_style (str) – The language style (‘glsl’, ‘hlsl’, ‘metal’, ‘spirv’)

Return type:

str

Returns:

The formatted array type string for the target language

crosstl.translator.codegen.array_utils.format_c_style_array_declaration(type_name, variable_name)

Format a declaration when the type string includes C-style array suffixes.

Converts “float[4]”, “vec3[]”, or “float[3][4]” into “float name[4]”, “vec3 name[]”, or “float name[3][4]”. Non-array type strings are returned as “type name”.

Return type:

str

crosstl.translator.codegen.array_utils.get_array_size_from_node(node)

Extract array size from an AST ArrayNode.

Parameters:

node – The ArrayNode to extract size from

Return type:

Optional[int]

Returns:

The array size as an integer, or None for dynamic arrays

crosstl.translator.codegen.array_utils.parse_array_type(type_name)

Parse an array type string into base type and size.

Parameters:

type_name (str) – The array type string (e.g., “float[4]”, “vec3[]”)

Return type:

Tuple[str, Optional[int]]

Returns:

Tuple of (base_type, size) where size is None for dynamic arrays

crosstl.translator.codegen.array_utils.split_array_type_suffix(type_name)

Split an array type string while preserving the full array suffix.

Unlike parse_array_type(), this keeps non-literal sizes such as “float[(2 + 1) * 2]” intact instead of treating them as unsized arrays.

Return type:

Tuple[str, str]