fmod/core/
thread.rs

Help
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 crate::{FmodResultExt, Result};
8use crate::{ThreadAffinity, ThreadType};
9use fmod_sys::*;
10
11/// Scheduling priority to assign a given thread to.
12pub mod priority {
13    use fmod_sys::*;
14
15    /// Lower bound of platform specific priority range.
16    pub const PLATFORM_MIN: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_PLATFORM_MIN;
17    /// Upper bound of platform specific priority range.
18    pub const PLATFORM_MAX: FMOD_THREAD_PRIORITY =
19        FMOD_THREAD_PRIORITY_PLATFORM_MAX as FMOD_THREAD_PRIORITY; // no idea why this is u32 (32768 fits in an i32)
20    /// For a given thread use the default listed below, i.e. [`FMOD_THREAD_TYPE_MIXER`] uses [`FMOD_THREAD_PRIORITY_MIXER`].
21    pub const DEFAULT: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_DEFAULT;
22    /// Low platform agnostic priority.
23    pub const LOW: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_LOW;
24    /// Medium platform agnostic priority.
25    pub const MEDIUM: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_MEDIUM;
26    /// High platform agnostic priority.
27    pub const HIGH: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_HIGH;
28    /// Very high platform agnostic priority.
29    pub const VERY_HIGH: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_VERY_HIGH;
30    /// Extreme platform agnostic priority.
31    pub const EXTREME: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_EXTREME;
32    /// Critical platform agnostic priority.
33    pub const CRITICAL: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_CRITICAL;
34    /// Default priority for [`FMOD_THREAD_TYPE_MIXER`].
35    pub const MIXER: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_MIXER;
36    /// Default priority for [`FMOD_THREAD_TYPE_FEEDER`].
37    pub const FEEDER: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_FEEDER;
38    /// Default priority for [`FMOD_THREAD_TYPE_STREAM`].
39    pub const STREAM: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_STREAM;
40    /// Default priority for [`FMOD_THREAD_TYPE_FILE`].
41    pub const FILE: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_FILE;
42    /// Default priority for [`FMOD_THREAD_TYPE_NONBLOCKING`].
43    pub const NONBLOCKING: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_NONBLOCKING;
44    /// Default priority for [`FMOD_THREAD_TYPE_RECORD`].
45    pub const RECORD: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_RECORD;
46    /// Default priority for [`FMOD_THREAD_TYPE_GEOMETRY`].
47    pub const GEOMETRY: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_GEOMETRY;
48    /// Default priority for [`FMOD_THREAD_TYPE_PROFILER`].
49    pub const PROFILER: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_PROFILER;
50    /// Default priority for [`FMOD_THREAD_TYPE_STUDIO_UPDATE`].
51    pub const STUDIO_UPDATE: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_STUDIO_UPDATE;
52    /// Default priority for [`FMOD_THREAD_TYPE_STUDIO_LOAD_BANK`].
53    pub const STUDIO_LOAD_BANK: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_STUDIO_LOAD_BANK;
54    /// Default priority for [`FMOD_THREAD_TYPE_STUDIO_LOAD_SAMPLE`].
55    pub const STUDIO_LOAD_SAMPLE: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_STUDIO_LOAD_SAMPLE;
56    /// Default priority for [`FMOD_THREAD_TYPE_CONVOLUTION1`].
57    pub const CONVOLUTION_1: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_CONVOLUTION1;
58    /// Default priority for [`FMOD_THREAD_TYPE_CONVOLUTION2`].
59    pub const CONVOLUTION_2: FMOD_THREAD_PRIORITY = FMOD_THREAD_PRIORITY_CONVOLUTION2;
60}
61
62/// Stack space available to the given thread.
63pub mod stack_size {
64    use fmod_sys::*;
65    /// For a given thread use the default listed below, i.e. [`FMOD_THREAD_TYPE_MIXER`] uses [`FMOD_THREAD_STACK_SIZE_MIXER`].
66    pub const DEFAULT: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_DEFAULT;
67    /// Default stack size for [`FMOD_THREAD_TYPE_MIXER`].
68    pub const MIXER: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_MIXER;
69    /// Default stack size for [`FMOD_THREAD_TYPE_MIXER`].
70    pub const FEEDER: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_FEEDER;
71    /// Default stack size for [`FMOD_THREAD_TYPE_STREAM`].
72    pub const STREAM: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_STREAM;
73    /// Default stack size for [`FMOD_THREAD_TYPE_FILE`].
74    pub const FILE: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_FILE;
75    /// Default stack size for [`FMOD_THREAD_TYPE_NONBLOCKING`].
76    pub const NONBLOCKING: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_NONBLOCKING;
77    /// Default stack size for [`FMOD_THREAD_TYPE_RECORD`].
78    pub const RECORD: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_RECORD;
79    /// Default stack size for [`FMOD_THREAD_TYPE_GEOMETRY`].
80    pub const GEOMETRY: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_GEOMETRY;
81    /// Default stack size for [`FMOD_THREAD_TYPE_PROFILER`].
82    pub const PROFILER: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_PROFILER;
83    /// Default stack size for [`FMOD_THREAD_TYPE_STUDIO_UPDATE`].
84    pub const STUDIO_UPDATE: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_STUDIO_UPDATE;
85    /// Default stack size for [`FMOD_THREAD_TYPE_STUDIO_LOAD_BANK`].
86    pub const STUDIO_LOAD_BANK: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_STUDIO_LOAD_BANK;
87    /// Default stack size for [`FMOD_THREAD_TYPE_STUDIO_LOAD_SAMPLE`].
88    pub const STUDIO_LOAD_SAMPLE: FMOD_THREAD_STACK_SIZE =
89        FMOD_THREAD_STACK_SIZE_STUDIO_LOAD_SAMPLE;
90    /// Default stack size for [`FMOD_THREAD_TYPE_CONVOLUTION1`].
91    pub const CONVOLUTION_1: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_CONVOLUTION1;
92    /// Default stack size for [`FMOD_THREAD_TYPE_CONVOLUTION2`].
93    pub const CONVOLUTION_2: FMOD_THREAD_STACK_SIZE = FMOD_THREAD_STACK_SIZE_CONVOLUTION2;
94}
95
96/// Specify the affinity, priority and stack size for all FMOD created threads.
97///
98/// You must call this function for the chosen thread before that thread is created for the settings to take effect.
99///
100/// Affinity can be specified using one (or more) of the [`ThreadAffinity`] constants or by providing the bits explicitly, i.e. (1<<3) for logical core three (core affinity is zero based).
101/// See platform documentation for details on the available cores for a given device.
102///
103/// Priority can be specified using one of the [`FMOD_THREAD_PRIORITY`] constants or by providing the value explicitly, i.e. (-2) for the lowest thread priority on Windows.
104/// See platform documentation for details on the available priority values for a given operating system.
105///
106/// Stack size can be specified explicitly, however for each thread you should provide a size equal to or larger than the expected default or risk causing a stack overflow at runtime.
107pub fn set_attributes(
108    kind: ThreadType,
109    affinity: ThreadAffinity,
110    priority: FMOD_THREAD_PRIORITY,
111    stack_size: FMOD_THREAD_STACK_SIZE,
112) -> Result<()> {
113    unsafe {
114        FMOD_Thread_SetAttributes(kind.into(), affinity.into(), priority, stack_size).to_result()
115    }
116}
fmod/core/thread.rs

fmod/core/
thread.rs
