fmod/core/
debug.rs

1// Copyright (c) 2024 Melody Madeline Lyons
2//
3// This Source Code Form is subject to the terms of the Mozilla Public
4// License, v. 2.0. If a copy of the MPL was not distributed with this
5// file, You can obtain one at https://mozilla.org/MPL/2.0/.
6
7use fmod_sys::*;
8use lanyard::Utf8CString;
9
10use crate::{FmodResultExt, Result};
11use std::ffi::{c_char, c_int};
12
13/// Specify the destination of log output when using the logging version of FMOD.
14#[derive(PartialEq, Eq, Debug)]
15pub enum DebugMode {
16    /// Default log location per platform, i.e. Visual Studio output window, stderr, `LogCat`, etc.
17    TTY,
18    /// Write log to specified file path.
19    File(Utf8CString),
20    /// Call specified callback with log information.
21    Callback(
22        unsafe extern "C" fn(
23            FMOD_DEBUG_FLAGS,
24            *const c_char,
25            c_int,
26            *const c_char,
27            *const c_char,
28        ) -> FMOD_RESULT,
29    ),
30}
31
32bitflags::bitflags! {
33    /// Specify the requested information to be output when using the logging version of FMOD.
34    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
35    pub struct DebugFlags: FMOD_DEBUG_FLAGS {
36        /// Disable all messages.
37        const NONE = FMOD_DEBUG_LEVEL_NONE;
38        /// Enable only error messages.
39        const ERROR = FMOD_DEBUG_LEVEL_ERROR;
40        /// Enable warning and error messages.
41        const WARNING = FMOD_DEBUG_LEVEL_WARNING;
42        /// Enable informational, warning and error messages (default).
43        const LOG = FMOD_DEBUG_LEVEL_LOG;
44        /// Verbose logging for memory operations, only use this if you are debugging a memory related issue.
45        const MEMORY = FMOD_DEBUG_TYPE_MEMORY;
46        /// Verbose logging for file access, only use this if you are debugging a file related issue.
47        const FILE = FMOD_DEBUG_TYPE_FILE;
48        /// Verbose logging for codec initialization, only use this if you are debugging a codec related issue.
49        const CODEC = FMOD_DEBUG_TYPE_CODEC;
50        /// Verbose logging for internal errors, use this for tracking the origin of error codes.
51        const TRACE = FMOD_DEBUG_TYPE_TRACE;
52        /// Verbose logging for whenever a [`Channel`] changes its virtual state.
53        #[cfg(fmod_gte_2_3_9)]
54        const VIRTUAL = FMOD_DEBUG_TYPE_VIRTUAL;
55        /// Display the time stamp of the log message in milliseconds.
56        const DISPLAY_TIMESTAMPS = FMOD_DEBUG_DISPLAY_TIMESTAMPS;
57        /// Display the source code file and line number for where the message originated.
58        const DISPLAY_LINENUMBERS = FMOD_DEBUG_DISPLAY_LINENUMBERS;
59        /// Display the thread ID of the calling function that generated the message.
60        const DISPLAY_THREAD = FMOD_DEBUG_DISPLAY_THREAD;
61    }
62}
63
64impl From<FMOD_DEBUG_FLAGS> for DebugFlags {
65    fn from(value: FMOD_DEBUG_FLAGS) -> Self {
66        DebugFlags::from_bits_truncate(value)
67    }
68}
69
70impl From<DebugFlags> for FMOD_DEBUG_FLAGS {
71    fn from(value: DebugFlags) -> Self {
72        value.bits()
73    }
74}
75
76/// Specify the level and delivery method of log messages when using the logging version of FMOD.
77///
78/// This function will return [`FMOD_RESULT::FMOD_ERR_UNSUPPORTED`] when using the non-logging (release) versions of FMOD.
79/// The logging version of FMOD can be recognized by the 'L' suffix in the library name, fmodL.dll or libfmodL.so for instance.
80///
81/// By default this crate links against non-logging versions of FMOD in release builds.
82/// This behaviour can be changed with the "fmod-sys/force-debug" feature.
83///
84/// Note that:
85///     [`DebugFlags::LOG`] produces informational, warning and error messages.
86///     [`DebugFlags::WARNING`] produces warnings and error messages.
87///     [`DebugFlags::ERROR`] produces error messages only.
88pub fn initialize(flags: DebugFlags, mode: DebugMode) -> Result<()> {
89    match mode {
90        DebugMode::TTY => unsafe {
91            FMOD_Debug_Initialize(flags.into(), FMOD_DEBUG_MODE_TTY, None, std::ptr::null())
92                .to_result()
93        },
94        DebugMode::File(file) => unsafe {
95            FMOD_Debug_Initialize(flags.into(), FMOD_DEBUG_MODE_FILE, None, file.as_ptr())
96                .to_result()
97        },
98        DebugMode::Callback(c) => unsafe {
99            FMOD_Debug_Initialize(
100                flags.into(),
101                FMOD_DEBUG_MODE_CALLBACK,
102                Some(c),
103                std::ptr::null(),
104            )
105            .to_result()
106        },
107    }
108}
fmod/core/debug.rs

fmod/core/
debug.rs
