Crate lf_gfx 

LucentFlux Graphics Library

This crate provides a collection of common utilities when writing wgpu programs. This library is made public since the utilities provided may be useful, but is not intended to be a general-purpose library and features will be added and removed as and when we need them.

Features

Fragment-only fullscreen-quad shader pipelines

Reduced boilerplate for fragment shaders run on fullscreen quads:

use lf_gfx::{LfDeviceExt, LfCommandEncoderExt};

// Standard pipeline creation pattern, but ending with `create_fragment_only_render_pipeline`:
let layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor { 
    label: Some("layout"), 
    bind_group_layouts: &[/* .. */], 
    push_constant_ranges:  &[/* .. */] 
});
let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
    label: Some("module"),
    source: wgpu::ShaderSource::Wgsl(
        /* .. */
    ),
});
let pipeline = device.create_fragment_only_render_pipeline(&lf_gfx::FragmentOnlyRenderPipelineDescriptor {
    label: Some("pipeline"),
    layout: Some(&layout),
    multisample: wgpu::MultisampleState::default(),
    fragment: wgpu::FragmentState { 
        module: &module, 
        entry_point: Some("main"), 
        targets: &[/* .. */] ,
        compilation_options: wgpu::PipelineCompilationOptions::default(),
    },
    multiview: None,
    cache: None,
});

let mut cmd = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
    label: Some("command encoder"),
});
let mut rp = cmd.begin_fragment_only_render_pass(&lf_gfx::FragmentOnlyRenderPassDescriptor {
    label: Some("renderpass"),
    color_attachments: &[/* .. */],
    stencil_attachment: None,
    timestamp_writes: None,
});
// No need to bind vertex buffers or even a unit vertex shader
rp.set_pipeline(&pipeline);
rp.draw();

Local Storage

use lf_gfx::local_storage;

local_storage::store("my_key", "a value").unwrap();

// Persists between runs
let stored = local_storage::load("my_key");
assert_eq!(stored, Some("a value".to_owned()));

Game API

struct MyGameCfg { /* .. */ }
#[derive(serde::Serialize, serde::Deserialize)]
enum MyGameLinearInputs { 
    Forward,
    Jump,
    /* .. */ 
}
#[derive(serde::Serialize, serde::Deserialize)]
enum MyGameVectorInputs { 
    Look,
    /* .. */ 
}

struct MyGame { /* .. */ }

impl lf_gfx::Game for MyGame {
    type InitData = MyGameCfg;
    type LinearInputType = MyGameLinearInputs;
    type VectorInputType = MyGameVectorInputs;

    fn title() -> &'static str {
        "My Game"
    }

    fn default_inputs(&self) -> lf_gfx::input::InputMap<MyGameLinearInputs, MyGameVectorInputs> {
        let mut inputs = lf_gfx::input::InputMap::empty();

        inputs.assign_linear(lf_gfx::input::KeyCode::KeyW, MyGameLinearInputs::Forward);
        inputs.assign_linear(lf_gfx::input::MouseInputType::ScrollUp, MyGameLinearInputs::Jump);

        inputs.assign_vector(lf_gfx::input::VectorInputType::MouseMove, MyGameVectorInputs::Look);

        return inputs;
    }

    fn init(data: &lf_gfx::GameData, init: Self::InitData) -> anyhow::Result<Self> {
        Ok(Self { /* .. */ })
    }

    fn window_resize(&mut self, data: &lf_gfx::GameData, new_size: winit::dpi::PhysicalSize<u32>) {
        /* .. */
    }

    fn handle_linear_input(
        &mut self,
        data: &lf_gfx::GameData,
        input: &Self::LinearInputType,
        activation: lf_gfx::input::LinearInputActivation,
    ) {
        /* .. */
    }

    fn handle_vector_input(
        &mut self,
        data: &lf_gfx::GameData,
        input: &Self::VectorInputType,
        activation: lf_gfx::input::VectorInputActivation,
    ) {
        /* .. */
    }

    fn render_to(&mut self, data: &lf_gfx::GameData, view: wgpu::TextureView) {
        /* .. */
    }
}

fn main() {
    use lf_gfx::LfGameExt;
    MyGame::run(MyGameCfg { /* .. */ });
}

Faster Non-cryptographic Hashing

let mut hs = lf_gfx::FastHashSet::default();
let mut hm = lf_gfx::FastHashMap::default();

hs.insert(10);
hm.insert(20, 30);

Modules

input

local_storage

A key-value store implemented either via a file next to the executable, or local browser storage on Web.

Structs

ExitFlag

A cloneable and distributable flag that can be cheaply queried to see if the game has exited.

FastHashState

FragmentOnlyRenderBundleEncoder

FragmentOnlyRenderBundleEncoderDescriptor

FragmentOnlyRenderPass

FragmentOnlyRenderPassDescriptor

FragmentOnlyRenderPipeline

FragmentOnlyRenderPipelineDescriptor

GameData

GameWindow

PaddedBufferInitDescriptor

Enums

GameCommand

A command sent to the game to change the game state

InputMode

Constants

BUFFER_PADDING

Some operations care about alignment in such a way that it is often easier to simply round all buffer sizes up to the nearest multiple of some power of two. This constant gives that power of two, and the corresponding LfDeviceExt::create_buffer_padded, [LfDeviceExt::new_buffer_init_padded] and LfQueueExt::write_buffer_padded all extend their data lengths to the nearest multiple of this constant.

Traits

Game

All of the callbacks required to implement a game. This API is built on top of a message passing event system, and so calls to the below methods may be made concurrently, in any order, and on different threads.

LfBindGroupLayoutEntryExt

Extensions to wgpu::BindGroupLayoutEntry.

LfBufferExt

Extensions to wgpu::Buffer.

LfCommandEncoderExt

Extensions to wgpu::CommandEncoder.

LfDeviceExt

Extensions to wgpu::Device.

LfGameExt

Extensions to an implemented game object.

LfLimitsExt

Extensions to wgpu::Limits.

LfQueueExt

Extensions to wgpu::Queue.

WindowSizeDependent

Something that needs remaking/resizing whenever the game window is resized

Functions

alert_dialogue

Produces a dialogue box with an okay response. Good for quick and dirty errors when something has gone very wrong.

block_on

Provides semi-equivalent functionality to pollster::block_on, but without crashing on the web.

is_html_tag_supported

Gives whether the current execution environment (i.e. Browser) supports the provided HTML tag. Returns true on native.

Type Aliases

FastHashMap

A non-cryptographic hash map

FastHashSet

A non-cryptographic hash set