Memory management library of gfx_hal
Switch branches/tags
Nothing to show
Clone or download
bors[bot] and karroffel Merge #19
19: updated gfx-hal r=omni-viral a=karroffel

Now works with the recent gfx-hal changes for better error handling.

Co-authored-by: karroffel <therzog@mail.de>
Latest commit e9bba2f Oct 25, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src updated gfx-hal Oct 25, 2018
.gitignore Initial commit Jan 26, 2018
.travis.yml Add bors config, renamed to gfx-memory Feb 21, 2018
Cargo.toml updated gfx-hal Oct 25, 2018
LICENSE-APACHE Initial commit Jan 26, 2018
LICENSE-MIT Fix of the initial error in license file Apr 13, 2018
README.md fix typo Oct 13, 2018
bors.toml Add bors config, renamed to gfx-memory Feb 21, 2018
rustfmt.toml fix: Improve documentation Jan 31, 2018

README.md

gfx-memory - graphics memory management for gfx-hal.

Build Status Docs Crates.io

This crate provides tools to manage GPU memory provided by gfx-hal.

The main tool is the MemoryAllocator trait, which can be used to allocate Blocks of memory. The most notable MemoryAllocator implementation is SmartAllocator which can be used as-is. All other allocators in this crate are used internally in SmartAllocator, but are also exposed for users who want to create their own implementations in case SmartAllocator don't satisfy their needs.

A Factory is also provided, that wraps the allocation logic in this crate, along with creation of memory resources on a Device (such as Buffer or Image). For most use cases, the Factory provides all capabilities needed to manage memory based resources on a gfx_hal::Device.

Example

Simple example of using SmartAllocator to create a vertex Buffer:

extern crate gfx_hal;
extern crate gfx_memory;

use std::error::Error;

use gfx_hal::{Backend, Device};
use gfx_hal::buffer::Usage;
use gfx_hal::memory::Properties;
use gfx_memory::{MemoryAllocator, SmartAllocator, Type, Block};

type SmartBlock<B> = <SmartAllocator<B> as MemoryAllocator<B>>::Block;

fn make_vertex_buffer<B: Backend>(
    device: &B::Device,
    allocator: &mut SmartAllocator<B>,
    size: u64,
) -> Result<(SmartBlock<B>, B::Buffer), Box<Error>> {
    // Create unbounded buffer object. It has no memory assigned.
    let ubuf: B::UnboundBuffer = device.create_buffer(size, Usage::VERTEX).map_err(Box::new)?;
    // Get memory requirements for the buffer.
    let reqs = device.get_buffer_requirements(&ubuf);
    // Allocate block of device-local memory that satisfy requirements for buffer.
    let block = allocator
        .alloc(device, (Type::General, Properties::DEVICE_LOCAL), reqs)
        .map_err(Box::new)?;
    // Bind memory block to the buffer.
    Ok(device
        .bind_buffer_memory(block.memory(), block.range().start, ubuf)
        .map(|buffer| (block, buffer))
        .map_err(Box::new)?)
}

This crate is mid-level and it requires the user to follow a few simple rules:

  • When memory blocks are to be freed, they must be returned to the allocator they were allocated from.
  • The same instance of Device must be used for allocating and freeing blocks.

Violating those rules may cause undefined behaviour.

License

Licensed under either of

at your option.

Contribution

We are a community project that welcomes contribution from anyone. If you're interested in helping out, you can contact us either through GitHub, or via gitter.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.