wwise-zig - Zig bindings to Audiokinetic Wwise (2022.1.13)

This package implement a native Zig binding for Audiokinetic Wwise. The included C binding is designed only to be used by the Zig binding. If you want to expand the C binding to be fully functional please submit any pull requests.

Each function name, structs and enums has been renamed to fit the Zig coding style. It should be easy to map to the Wwise SDK documentation.

Each major version of Wwise is contained within a branch. Select the correct branch and tag when importing the library with the Zig package manager.

The library assumes that you installed Wwise using the Wwise Launcher. We do not distribute any binary from Audiokinetic.

This is a 3rd party binding and it is not affiliated with Audiokinetic.

Zig version

This library uses zig nominated 2024.3.0-mach. To install using zigup:

zigup 0.12.0-dev.3180+83e578a18

Versioning info

This binding mimic the versioning of Wwise but add the Zig binding version at the end.

Example:

2022.1.9-zig0

• 2022 = year
• 1 = major Wwise version
• 9 = minor Wwise version
• -zig0 = Zig binding version

Supported platforms

• On Windows, the default GNU ABI is not supported, always use the MSVC ABI
• On Windows, we always use the latest supported Visual Studio (currently 2022)
• On Linux, the default I/O hooks are currently not supported (see #1)
• UWP is gonna be deprecated so it is not supported
• No support for consoles yet

Import it in your project

1. Add this repo in your build.zig.zon file, you'll need to add the hash and update the commit hash to the latest commit in the branch

   .@"wwise-zig" = .{
   .url = "https://github.com/Cold-Bytes-Games/wwise-zig/archive/90cdc6877369b55af3ee2dfcf091dc547ed59f03.tar.gz",
   .hash = "122053d2ec67ebe8a47b45ac32ddf41283b27c3519196b6730d9b826a463d1294299",
   },

2. Import the dependency in your build.zig. See the Usage section for the list of available options.

const std = @import("std");
const wwise_zig = @import("wwise-zig");

pub fn build(b: *std.Build) !void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const wwise_dependency = b.dependency("wwise-zig", .{
        .target = target,
        .optimize = optimize,
        .use_communication = true,
        .use_default_job_worker = true,
        .use_spatial_audio = true,
        .use_static_crt = true,
        .include_file_package_io_blocking = true,
        .configuration = .profile,
        .static_plugins = @as([]const []const u8, &.{
            "AkToneSource",
            "AkParametricEQFX",
            "AkDelayFX",
            "AkPeakLimiterFX",
            "AkRoomVerbFX",
            "AkStereoDelayFX",
            "AkSynthOneSource",
            "AkAudioInputSource",
            "AkVorbisDecoder",
        }),
    });

    const exe = b.addExecutable(.{
        .name = "wwise-zig-demo",
        .root_source_file = .{ .path = "src/main.zig" },
        .target = target,
        .optimize = optimize,
    });

    exe.root_module.addImport("wwise-zig", wwise_dependency.module("wwise-zig"));
}

Usage

We recommend using AK as your import name to match closely with the C++ API.

const AK = @import("wwise-zig");

pub fn main() !void {
    var memory_settings: AK.AkMemSettings = undefined;
    AK.MemoryMgr.getDefaultSettings(&memory_settings);

    try AK.MemoryMgr.init(&memory_settings);
    defer AK.MemoryMgr.term();
}

You can also look at the Integration Demo ported to Zig here for how the API is used in a sample application: https://github.com/Cold-Bytes-Games/wwise-zig-demo

Handling AkOsChar and C null-terminated strings

wwise-zig is trying to save allocations when calling functions that accepts strings by using stack-allocated space to convert to const AkOsChar*/const char* or use a fallback allocator if the string is bigger than the stack size.

You can customize the size allocated by modifying the string_stack_size when importing the dependency.

Each function that handle strings looks similar to this:

pub fn dumpToFile(fallback_allocator: std.mem.Allocator, filename: []const u8) !void {
    var stack_char_allocator = common.stackCharAllocator(fallback_allocator);
    var allocator = stack_char_allocator.get();

    const filename_oschar = try common.toOSChar(allocator, filename);
    defer allocator.free(filename_oschar);

    c.WWISEC_AK_MemoryMgr_DumpToFile(filename_oschar);
}

Handling C++ inheritance

You can create derivated Zig struct from Wwise C++ clases that have virtual methods. Each binded class has a FunctionTable object like IAkIOHookDeferredBatch here:

pub const IAkIOHookDeferredBatch = opaque {
    pub const FunctionTable = extern struct {
        destructor: *const fn (self: *IAkIOHookBlocking) callconv(.C) void,
        close: *const fn (self: *IAkIOHookBlocking, in_file_desc: *AkFileDesc) callconv(.C) common.AKRESULT,
        get_block_size: *const fn (self: *IAkIOHookBlocking, in_file_desc: *AkFileDesc) callconv(.C) u32,
        get_device_desc: *const fn (self: *IAkIOHookBlocking, out_device_desc: *stream_interfaces.NativeAkDeviceDesc) callconv(.C) void,
        get_device_data: *const fn (self: *IAkIOHookBlocking) callconv(.C) u32,
        batch_read: *const fn (
            self: *IAkIOHookDeferredBatch,
            in_num_transfers: u32,
            in_transfer_items: [*]BatchIoTransferItem,
            in_batch_io_callback: AkBatchIOCallback,
            io_dispatch_results: [*]common.AKRESULT,
        ) callconv(.C) common.AKRESULT,
        batch_write: *const fn (
            self: *IAkIOHookDeferredBatch,
            in_num_transfers: u32,
            in_transfer_items: [*]BatchIoTransferItem,
            in_batch_io_callback: AkBatchIOCallback,
            io_dispatch_results: [*]common.AKRESULT,
        ) callconv(.C) common.AKRESULT,
        batch_cancel: *const fn (
            self: *IAkIOHookDeferredBatch,
            in_num_transfers: u32,
            in_transfer_items: [*]BatchIoTransferItem,
            io_cancel_all_transfers_for_this_file: [*]*bool,
        ) callconv(.C) void,
    };
}

On the glue side, we inherit from the interface and call those functions with the instance of your Zig struct.

Each class has a method createInstance() and destroyInstance that are used to create an instance of your own derivated struct. It uses AK memory manager function to allocate the instance with the AkMemID_Integration memory tag.

var zig_io_blocking = ZigTestIAkOHookBlocking{};
var native_io_blocking = AK.StreamMgr.IAkIOHookBlocking.createInstance(
            &zig_io_blocking,
            &AK.StreamMgr.IAkIOHookBlocking.FunctionTable{
                .destructor = @ptrCast(&ZigTestIAkOHookBlocking.destructor),
                .close = @ptrCast(&ZigTestIAkOHookBlocking.close),
                .get_block_size = @ptrCast(&ZigTestIAkOHookBlocking.getBlockSize),
                .get_device_desc = @ptrCast(&ZigTestIAkOHookBlocking.getDeviceDesc),
                .get_device_data = @ptrCast(&ZigTestIAkOHookBlocking.getDeviceData),
                .read = @ptrCast(&read),
                .write = @ptrCast(&write),
            },
        );
defer AK.StreamMgr.IAkIOHookBlocking.destroyInstance(native_io_blocking);

However we recommend creating a helper function in your struct to create the correct instance with the function table properly filled.

Here's a quick sample of a derivated IAkOHookBlocking struct from our test suite:

const ZigTestIAkOHookBlocking = struct {
    destructor_called: bool = false,
    close_called: bool = false,
    get_block_size_called: bool = false,
    get_device_desc_called: bool = false,
    get_device_data_called: bool = false,
    read_called: bool = false,
    write_called: bool = false,
    close_size: i64 = 0,

    pub fn destructor(self: *ZigTestIAkOHookBlocking) callconv(.C) void {
        self.destructor_called = true;
    }

    pub fn close(self: *ZigTestIAkOHookBlocking, in_file_desc: *AK.StreamMgr.AkFileDesc) callconv(.C) AK.AKRESULT {
        self.close_size = in_file_desc.file_size;
        self.close_called = true;

        return .success;
    }

    pub fn getBlockSize(self: *ZigTestIAkOHookBlocking, in_file_desc: *AK.StreamMgr.AkFileDesc) callconv(.C) u32 {
        _ = in_file_desc;
        self.get_block_size_called = true;
        return 512;
    }

    pub fn getDeviceDesc(self: *ZigTestIAkOHookBlocking, out_device_desc: *AK.NativeAkDeviceDesc) callconv(.C) void {
        self.get_device_desc_called = true;

        var zig_device_desc = AK.AkDeviceDesc{};
        zig_device_desc.can_write = false;
        zig_device_desc.can_read = true;
        zig_device_desc.device_name = "wwise-zig IO";

        out_device_desc.* = zig_device_desc.toC() catch unreachable;
    }

    pub fn getDeviceData(self: *ZigTestIAkOHookBlocking) callconv(.C) u32 {
        self.get_device_data_called = true;
        return 4269;
    }

    pub fn read(self: *ZigTestIAkOHookBlocking, in_file_desc: *AK.StreamMgr.AkFileDesc, in_heuristics: *AK.StreamMgr.AkIoHeuristics, out_buffer: ?*anyopaque, in_transfer_info: *AK.StreamMgr.AkIOTransferInfo) callconv(.C) AK.AKRESULT {
        _ = in_file_desc;
        _ = in_heuristics;

        self.read_called = true;

        if (out_buffer) |checked_buffer| {
            var read_buffer = @as([*]u8, @ptrCast(checked_buffer));
            @memset(read_buffer[in_transfer_info.file_position..in_transfer_info.requested_size], 0xC1);
        }

        return .success;
    }

    pub fn write(self: *ZigTestIAkOHookBlocking, in_file_desc: *AK.StreamMgr.AkFileDesc, in_heuristics: *AK.StreamMgr.AkIoHeuristics, in_data: ?*anyopaque, in_transfer_info: *AK.StreamMgr.AkIOTransferInfo) callconv(.C) AK.AKRESULT {
        _ = in_heuristics;
        _ = in_transfer_info;
        _ = in_data;
        _ = in_file_desc;

        self.write_called = true;

        return .success;
    }

    pub fn createIAkIOHookBlocking(self: *ZigTestIAkOHookBlocking) *AK.StreamMgr.IAkIOHookBlocking {
        return AK.StreamMgr.IAkIOHookBlocking.createInstance(
            self,
            &AK.StreamMgr.IAkIOHookBlocking.FunctionTable{
                .destructor = @ptrCast(&destructor),
                .close = @ptrCast(&close),
                .get_block_size = @ptrCast(&getBlockSize),
                .get_device_desc = @ptrCast(&getDeviceDesc),
                .get_device_data = @ptrCast(&getDeviceData),
                .read = @ptrCast(&read),
                .write = @ptrCast(&write),
            },
        );
    }
};

Use the default I/O hook(s) from the SDK

First you need to include at least one I/O hook in the build options.

All the default I/O are included in the IOHooks namespace from the wwise-zig package.

Use the create and destroy function with a Zig allocator to create a instance of the I/O hook.

After that, you need to call init and setBasePath like in C++

const std = @import("std");
const AK = @import("wwise-zig");

pub fn main() !void {
    var io_hook = try AK.IOHooks.CAkFilePackageLowLevelIODeferred.create(std.testing.allocator);
    defer io_hook.destroy(std.testing.allocator);

    try io_hook.init(device_settings, false);
    defer io_hook.term();

    try io_hook.setBasePath(std.testing.allocator, ".");

    const loaded_package_id = try io_hook.loadFilePackage(std.testing.allocator, "MyWwiseData.pck");
}

Generate the Sound Banks with the Zig build system

We are bundling a build step to generate the sound banks. To use it:

1. Include the wwise-zig dependency in youtr build.zig.zon file.
2. Import the wwise-zig module in your build.zig.
3. Call addGenerateSooundBanksStep() and pass the std.Build instance and some optioons.
4. After that, it is recommended that you add the generate sound banks steps as a dependency of your compile step.

Example:

const std = @import("std");
const wwise_zig = @import("wwise-zig");

pub fn build(b: *std.Build) !void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const build_soundbanks_step = try wwise_zig.addGenerateSoundBanksStep(b, "WwiseProject/IntegrationDemo.wproj", .{
        .target = target,
    });

     const exe = b.addExecutable(.{
        .name = "wwise-zig-demo",
        .root_source_file = .{ .path = "src/main.zig" },
        .target = target,
        .optimize = optimize,
    });
    exe.step.dependOn(&build_soundbanks_step.step);

    // [...]
}

Generate a zig module with Wwise ID

If specified in the Wwise project settings, you can generate a C header file that contains all the unique ID of your events, soundbanks, states, switch, game parameters. We include a way to parse that header file and generate a Zig module on the fly.

You need to pass the main wwise-zig module to the function because we use AkUniqueID from the main module.

It is recommended that you add a dependency to the generated sound banks step if you use it in your build.zig file.

const std = @import("std");
const wwise_zig = @import("wwise-zig");

pub fn build(b: *std.Build) !void {
    // [...]
     const wwise_id_module = wwise_zig.generateWwiseIDModule(b, "WwiseProject/GeneratedSoundBanks/Wwise_IDs.h", wwise_package.module, .{
        .previous_step = &build_soundbanks_step.step,
    });

    exe.addModule("wwise-ids", wwise_id_module);

License

See LICENSE for more info.