Rust for Dreamcast

Creating a Rust project using kos-ports libraries

The gldc-cube example demonstrates creating a rotating 3D cube using Rust as the primary language, while calling C functions provided by the GLdc library available in kos-ports. This project's initial setup is done the same as the above hello example.

For this example, we'll need to convert JPEG textures to VQ-encoded textures at compile time using the vqenc utility includes with KallistiOS. To do this, we'll add a build.rs file to the root of the crate with the following code (abridged to show the conversion of only one texture):

fn main() {
    let kos_base = std::env::var("KOS_BASE").expect("Missing $KOS_BASE -- KallistiOS environment not sourced!");
    let vqenc_cmd = kos_base + "/utils/vqenc/vqenc";
    Command::new(&vqenc_cmd)
        .arg("-t")
        .arg("-v")
        .arg("rsrc/tex_claw.jpg")
        .output()
        .expect("vqenc on tex_claw.jpg failed!");
}

The texture files are then included in our project using the include_bytes! macro.

We will need to link the GLdc library in this example, but we don't need to do anything special to add the paths to this library, because adding the common paths to KallistiOS libraries is already done for us in the kos-rs crate. However, if in your project you need to include a separate unique library path, you can add it in your build.rs like so:

#![allow(unused)]
fn main() {
println!("cargo:rustc-link-search=native={}", lib_path);
}

The workings of this example's source code are too great to detail here line-by-line, but the example demonstrates how to use GLdc via the gldc-sys crate, which contains unsafe/raw bindings to GLdc. Check out this crate's source code for an example of declaring and binding external C functions, constants, and structures so they can be used in Rust code. Since the entirety of the gldc-cube example uses C FFI functions without safe wrappers, the main() source is wrapped in unsafe {}. In the future, this would be much less necessary as higher level safe Rust bindings to KallistiOS and other libraries become mature.