Skip to content
This repository has been archived by the owner on Jun 20, 2022. It is now read-only.

Latest commit

 

History

History
132 lines (99 loc) · 9.57 KB

SPEC.md

File metadata and controls

132 lines (99 loc) · 9.57 KB
Raw

File Format and Runtime Behavior

The only required input to grimoire is a TOML configuration file. This configuration file defines a series of draw passes and resources. This document describes the schema for how you define these draw passes and resources, and documents the GLSL code that's automatically prepended to your shader code at runtime.

Configuration

  • The configuration is composed of two main parts: named resources and an ordered list of passes
  • A resource is an umbrella term for anything that can be converted into a texture and sampled in a shader. Examples include images, video, webcam, keyboard input, g-streamer pipelines, and framebuffer objects.
  • A pass defines a single draw call, including vertex and fragment shaders, the number of primitives (points, lines, triangles, triangle fan, etc.), draw target (A named resource buffer), and uniform names to bind to declared resources.
  • Passes draw into a buffer by specifying the buffer key. If no buffer key is present, the pass draws to the default framebuffer
  • Passes configure uniform samplers for use in the shader code by specifying the desired uniform name as a key, and a resource name for the value
    • You can give your uniforms any name, except "buffer", "draw", "blend", "depth", "clear"
    • Uniform declarations are automatically inserted into your code before compilation
  • Passes configure the primitive type (triangles, points, lines) and count to draw, blending, depth testing, and the clear color

Resources

A resource is a TOML table that configures a texture object or a framebuffer with color attachments. Below is a list of all resource scehmas. Note that all relative paths are relative to the shader input file.

Buffer

Configures a framebuffer object that a pass can draw to. This is the only resource type that can be referenced by the pass buffer configuration.

  • buffer=list[{"u8", "f16", "f32"}], Required, the format of each color attachment
  • width=u32, Optional, defauls to the window width
  • height=u32 , Optional, defaults to the window height
  • scale=f32, Optional, scales the width and height of the buffer, defaults to 1.0
  • components=u32, Optional, the number of components per pixel (1=R, 2=RG, 3=RGB, 4=RGBA), defaults to 4
  • depth=bool, Optional, specify the depth attachment, defaults to true with U24 format
  • depth={"u16", "u24", "u32", "f32"}, Optional, specify the depth attachment format explicitly

Image

  • image=string: Required, relative path to an image file. Supports png, jpeg, gif, bmp, ico, tiff, webp, pnm
  • flipv=bool: Optional, flip the image vertically before uploading to the GPU, defaults to true
  • fliph=bool: Optional, flip the image horizontally before uploading to the GPU, defaults to false

Texture2D

  • texture2D=string: Required, relative path to a file containing 2D texture data
  • width=u32: Required, the texture width
  • height=u32: Required, the texture height
  • format=string: Required, the texture format, accepts the following strings: "ru8", "rf16", "rf32", "rgu8", "rgf16", "rgf32", "rgbu8", "rgbf16", "rgbf32", "rgbau8", "rgbaf16", "rgbaf32", "bgru8", "bgrf16", "bgrf32", "bgrau8", "bgraf16", "bgraf32"

Texture3D

  • texture3D=string: Required, relative path to a file containing 3D texture data
  • width=u32: Required, the texture width
  • height=u32: Required, the texture height
  • depth=u32: Required, the texture depth
  • format=string: Required, the texture format, accepts the following strings: "ru8", "rf16", "rf32", "rgu8", "rgf16", "rgf32", "rgbu8", "rgbf16", "rgbf32", "rgbau8", "rgbaf16", "rgbaf32", "bgru8", "bgrf16", "bgrf32", "bgrau8", "bgraf16", "bgraf32"

Cubemap

  • left=string: Required, relative path to an image file for the left cubemap face
  • right=string: Required, relative path to an image file for the right cubemap face
  • front=string: Required, relative path to an image file for the front cubemap face
  • back=string: Required, relative path to an image file for the back cubemap face
  • top=string: Required, relative path to an image file for the top cubemap face
  • bottom=string: Required, relative path to an image file for the bottom cubemap face
  • flipv=bool: Optional, flip the image vertically before uploading to the GPU, defaults to true
  • fliph=bool: Optional, flip the image horizontally before uploading to the GPU, defaults to false

Each face supports the same file formats as image input.

Keyboard

  • keyboard=bool: Required, the value is ignored.

Webcam

  • webcam=bool: Required, the value is ignored.

Microphone

  • microphone=bool: Required, the value is ignored.

Video

  • video=string: Required, relative path to a video file OR a uri. File support depends on your GStreamer installation. Uses playbin internally. Users can use playbin2 and playbin3 by defining the enviornment variables USE_PLAYBIN2=1 and USE_PLAYBIN3=1 , respectively.

Audio

  • audio=string: Required, relative path to an audio file OR a uri. File support depends on your GStreamer installation. Uses uridecodebin internally.

Pipeline

  • pipeline=string: Required, a GStreamer gst-launch pipeline description. grimoire assumes that the pipeline description contains an appsink element with name appsink and that the pipeline produces samples with video caps.

Passes

Passes are defined as an array of tables and are drawn in the order listed in the configuration.

  • buffer=string: Optional, the buffer to draw into. If not specified, the pass draws to the default framebuffer
  • draw={mode=string{"triangles", "points", ...}, count=u32}: configures the draw primitive and number of vertices to draw, defaults to mode="triangles", count=1. Valid mode values: "triangles", "points", "lines", "triangle-fan", "triangle-strip", "line-strip", "line-loop"
  • depth=string{"less",...}: depth testing, defaults to disabled. Valid values: "never", "less", "equal", "less-equal", "greater", "not-equal", "greater-equal", "always"
  • depth={func=string{"less",...}, write=bool}: Specify the depth testing function and if the pass should write to the depth buffer. write defaults to true.
  • blend={src=string{"one",..}, dest=string{"one-minus-src-alpha",..}}: blend functions, defaults to disabled. Valid src and dest values: "zero", "one", "src-color", "one-minus-src-color", "dst-color", "one-minus-dst-color", "src-alpha", "one-minus-src-alpha", "dst-alpha", "one-minus-dst-alpha"
  • clear=[f32;4]: Optional, configures the clear color (RGBA) for the pass
  • clear=[f32;5]: Optional, configures the clear color (RGBA) and clear depth for the pass. The depth value is in the last component.
  • clear={color=[f32;4], depth=f32}: Optional, configures the clear color (RGBA) (optional) and the clear depth (optional) for the pass.

All other key-value pairs associate a uniform sampler with a resource. grimoire uses the key name to generate uniform sampler declarations that are inserted into your code. The valid values are:

  • samplerName=string: a resource name, defaults to wrap="repeat", filter="mipmap" (filter="linear" for Texture3D inputs)
  • samplerName={resource=string, wrap="clamp","repeat", filter="linear","nearest","mipmap"}: requires resource, defaults to wrap="repeat", filter="mipmap"

Uniform Insertion

For each uniform sampler resource pairs in pass, grimoire inserts the following uniform declarations into your shader code before compilation:

  • uniform SAMPLERTYPE_FROM_VAL NAME: The texture sampler
  • uniform vec3 NAME_Resolution: The resolution of the texure resource, z contains the aspect ratio
  • uniform float NAME_Time: The playback time of the texture resource

Use names like iChannel0, iChannel1, ... iChannelN to make it easier to copy-paste your shader code into shadertoy.

GLSL

grimoire prepends the following GLSL code to your shader code:

  • The #version directive. You can explicitly control this value by the --gl command-line argument.
  • Uniform declarations required by grimoire for data such as current time, current frame, mouse state, window resolution, etc.. At the time of writing, the uniform names match the uniform names used on shadertoy.
  • Uniform sampler declarations of the appropriate type for the uniforms defined in the pass configuration.

You can use #include statements in your glsl shaders (both #include "common.glsl" and #include <common.glsl> will work). grimoire watches included shader files for changes for live updates. See https://github.com/jshrake/glsl-include for more details on specific syntax support.