Architecture note for a custom procedural texture node in Blender using the Python API

Problem and takeaway

You need a reusable procedural texture that works in both Eevee and Cycles, exposes artist‑friendly controls, and degrades gracefully when GPU resources are unavailable. The following architecture note outlines the minimal design, trust boundaries, operational checks, failure modes, and the conditions that would trigger a redesign.

Requirements

• Expose user‑controlled properties: color (RGB), scale (float), noise type (enum: Perlin, Voronoi, Musgrave).
• Function in Eevee and Cycles, on CPU and GPU.
• Persist with the .blend file and be reusable across projects.
• Validate inputs, keep internal shader state private, and avoid modifying global Blender data.
• Provide runtime checks for GPU support and fallback to CPU when needed.

Smallest suitable design

A single Python module registers a custom node type that inherits from bpy.types.Node. The node defines:

• Three FloatProperty fields for color channels.
• One FloatProperty for scale.
• One EnumProperty for noise type.
• A draw() method that lays out these properties in the node UI.
• A process() method that either executes a pure‑Python noise function (CPU path) or compiles a GLSL fragment shader and dispatches it via GPUNodeTree (GPU path).
• Two output sockets: a color vector and a float factor, both usable as texture inputs in material node trees.

Example node registration (illustrative)

import bpy
from bpy.props import FloatProperty, EnumProperty

class PROCEDURAL_TEXTURE_Node(bpy.types.Node):
    bl_idname = 'PROCEDURAL_TEXTURE_Node'
    bl_label = 'Procedural Texture'
    bl_icon = 'TEXTURE'

    # UI properties
    color_r: FloatProperty(name='R', default=0.8, min=0.0, max=1.0, subtype='FACTOR')
    color_g: FloatProperty(name='G', default=0.8, min=0.0, max=1.0, subtype='FACTOR')
    color_b: FloatProperty(name='B', default=0.8, min=0.0, max=1.0, subtype='FACTOR')
    scale: FloatProperty(name='Scale', default=1.0, min=0.01, max=100.0)
    noise_type: EnumProperty(
        name='Noise Type',
        items=[('PERLIN', 'Perlin', ''), ('VORONOI', 'Voronoi', ''), ('MUSGRAVE', 'Musgrave', '')],
        default='PERLIN'
    )

    def init(self, context):
        self.outputs.new('NodeSocketVectorColor', 'Color')
        self.outputs.new('NodeSocketFloat', 'Factor')

    def draw_buttons(self, context, layout):
        layout.prop(self, 'color_r')
        layout.prop(self, 'color_g')
        layout.prop(self, 'color_b')
        layout.prop(self, 'scale')
        layout.prop(self, 'noise_type')

    def process(self):
        # Pseudocode: choose CPU or GPU path based on runtime check
        if self._gpu_available():
            self._compile_and_run_glsl()
        else:
            self._run_cpu_noise()

    # Helper methods (_gpu_available, _compile_and_run_glsl, _run_cpu_noise) omitted for brevity

def register():
    bpy.utils.register_class(PROCEDURAL_TEXTURE_Node)

def unregister():
    bpy.utils.unregister_class(PROCEDURAL_TEXTURE_Node)

if __name__ == "__main__":
    register()

Trust and data boundaries

• User‑supplied values (color, scale, noise type) are validated against the property definitions (range, enum).
• Internal state such as compiled shader handles is stored as private attributes on the node instance (self._shader_handle) and never exposed via Blender’s data API.
• The node only writes to its own properties; it does not create, delete, or modify data blocks outside its scope.

Operational checks

1. On node creation (init), query bpy.app.graphics_engine and attempt to create a minimal GPUNodeTree. If this fails, set a flag self._gpu_capable = False.
2. Before each frame (process call), verify the shader compile status via GPU.shader.get_info(). On failure, log a warning and switch to the CPU path for that frame.
3. Monitor GPU memory usage through GPU.stats.get('memory_used'). If usage exceeds a configurable threshold (e.g., 150 MB), emit a popup warning and suggest reducing scale or noise complexity.

Failure modes

• Unsupported GPU driver: Shader compilation returns an error; the node falls back to CPU, which may cause visual differences if the GPU path used features unavailable in the CPU implementation.
• Invalid property values: Although the UI clamps floats, scripted changes could bypass validation, leading to runtime exceptions in the noise function.
• Heavy procedural load: High octave counts or large scale values increase CPU cycles per pixel, potentially dropping frame‑rate in the viewport.
• Referencing deleted data: If the node stores a reference to a texture or image data block that is later removed, Blender may crash when the node tries to access it.

Conditions that would change the design

• Migration to Blender 4.0+ where the node system adopts a unified NodeTree API; the current bpy.types.Node subclass would need to be refactored to use the new registration pattern.
• Requirement for distributed rendering (e.g., off‑loading to a render farm). In that case the node should expose a lightweight REST or message‑queue interface that external workers can call, keeping the Blender‑side node as a thin proxy.
• Need for additional output types (e.g., normal vector) that exceed the current two‑socket design; the node class would be extended with extra output sockets and corresponding shader code.

Practical verification steps

1. Start a fresh Blender session on the target version (e.g., 3.6 LTS). Run the registration script via the Text Editor.
2. Open the Shader Editor, press Shift+A → Texture → Procedural Texture. Confirm the node appears with the expected controls.
3. Create a simple material using the node’s Color output to drive a Principled BSDF’s Base Color. Render a still frame with Eevee and then with Cycles; compare the output to a CPU‑only reference render (disable GPU in Preferences).
4. Play a short animation while watching the System Console for GPU shader compile warnings. Introduce a driver that lacks OpenGL 4.5 support and verify the node still renders via the CPU path.
5. Increase the Scale property to extreme values (e.g., 100) and monitor viewport FPS; note any slowdown and adjust the scale back to a usable range.

Limitations

The design assumes that the procedural noise can be expressed equivalently in GLSL and pure Python. Complex noise functions that rely on CPU‑specific libraries may not have a direct GPU counterpart, leading to divergence between paths. Additionally, the node does not handle automatic updates when linked libraries change; users must reload the node or reopen the .blend file to pick up external modifications.