examples/aldebug.cpp

   1 /*
   2  * OpenAL Debug Context Example
   3  *
   4  * Copyright (c) 2024 by Chris Robinson <chris.kcat@gmail.com>
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a copy
   7  * of this software and associated documentation files (the "Software"), to deal
   8  * in the Software without restriction, including without limitation the rights
   9  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  10  * copies of the Software, and to permit persons to whom the Software is
  11  * furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in
  14  * all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  22  * THE SOFTWARE.
  23  */
  24
  25 /* This file contains an example for using the debug extension. */
  26
  27 #include <algorithm>
  28 #include <array>
  29 #include <cassert>
  30 #include <cstdio>
  31 #include <memory>
  32 #include <string>
  33 #include <string_view>
  34 #include <vector>
  35
  36 #include "AL/al.h"
  37 #include "AL/alc.h"
  38 #include "AL/alext.h"
  39
  40 #include "alspan.h"
  41 #include "fmt/core.h"
  42
  43 #include "win_main_utf8.h"
  44
  45 namespace {
  46
  47 using namespace std::string_view_literals;
  48
  49 struct DeviceCloser {
  50     void operator()(ALCdevice *device) const noexcept { alcCloseDevice(device); }
  51 };
  52 using DevicePtr = std::unique_ptr<ALCdevice,DeviceCloser>;
  53
  54 struct ContextDestroyer {
  55     void operator()(ALCcontext *context) const noexcept { alcDestroyContext(context); }
  56 };
  57 using ContextPtr = std::unique_ptr<ALCcontext,ContextDestroyer>;
  58
  59
  60 constexpr auto GetDebugSourceName(ALenum source) noexcept -> std::string_view
  61 {
  62     switch(source)
  63     {
  64     case AL_DEBUG_SOURCE_API_EXT: return "API"sv;
  65     case AL_DEBUG_SOURCE_AUDIO_SYSTEM_EXT: return "Audio System"sv;
  66     case AL_DEBUG_SOURCE_THIRD_PARTY_EXT: return "Third Party"sv;
  67     case AL_DEBUG_SOURCE_APPLICATION_EXT: return "Application"sv;
  68     case AL_DEBUG_SOURCE_OTHER_EXT: return "Other"sv;
  69     }
  70     return "<invalid source>"sv;
  71 }
  72
  73 constexpr auto GetDebugTypeName(ALenum type) noexcept -> std::string_view
  74 {
  75     switch(type)
  76     {
  77     case AL_DEBUG_TYPE_ERROR_EXT: return "Error"sv;
  78     case AL_DEBUG_TYPE_DEPRECATED_BEHAVIOR_EXT: return "Deprecated Behavior"sv;
  79     case AL_DEBUG_TYPE_UNDEFINED_BEHAVIOR_EXT: return "Undefined Behavior"sv;
  80     case AL_DEBUG_TYPE_PORTABILITY_EXT: return "Portability"sv;
  81     case AL_DEBUG_TYPE_PERFORMANCE_EXT: return "Performance"sv;
  82     case AL_DEBUG_TYPE_MARKER_EXT: return "Marker"sv;
  83     case AL_DEBUG_TYPE_PUSH_GROUP_EXT: return "Push Group"sv;
  84     case AL_DEBUG_TYPE_POP_GROUP_EXT: return "Pop Group"sv;
  85     case AL_DEBUG_TYPE_OTHER_EXT: return "Other"sv;
  86     }
  87     return "<invalid type>"sv;
  88 }
  89
  90 constexpr auto GetDebugSeverityName(ALenum severity) noexcept -> std::string_view
  91 {
  92     switch(severity)
  93     {
  94     case AL_DEBUG_SEVERITY_HIGH_EXT: return "High"sv;
  95     case AL_DEBUG_SEVERITY_MEDIUM_EXT: return "Medium"sv;
  96     case AL_DEBUG_SEVERITY_LOW_EXT: return "Low"sv;
  97     case AL_DEBUG_SEVERITY_NOTIFICATION_EXT: return "Notification"sv;
  98     }
  99     return "<invalid severity>"sv;
 100 }
 101
 102 auto alDebugMessageCallbackEXT = LPALDEBUGMESSAGECALLBACKEXT{};
 103 auto alDebugMessageInsertEXT = LPALDEBUGMESSAGEINSERTEXT{};
 104 auto alDebugMessageControlEXT = LPALDEBUGMESSAGECONTROLEXT{};
 105 auto alPushDebugGroupEXT = LPALPUSHDEBUGGROUPEXT{};
 106 auto alPopDebugGroupEXT = LPALPOPDEBUGGROUPEXT{};
 107 auto alGetDebugMessageLogEXT = LPALGETDEBUGMESSAGELOGEXT{};
 108 auto alObjectLabelEXT = LPALOBJECTLABELEXT{};
 109 auto alGetObjectLabelEXT = LPALGETOBJECTLABELEXT{};
 110 auto alGetPointerEXT = LPALGETPOINTEREXT{};
 111 auto alGetPointervEXT = LPALGETPOINTERVEXT{};
 112
 113
 114 int main(al::span<std::string_view> args)
 115 {
 116     /* Print out usage if -h was specified */
 117     if(args.size() > 1 && (args[1] == "-h" || args[1] == "--help"))
 118     {
 119         fmt::println(stderr, "Usage: {} [-device <name>] [-nodebug]", args[0]);
 120         return 1;
 121     }
 122
 123     /* Initialize OpenAL. */
 124     args = args.subspan(1);
 125
 126     auto device = DevicePtr{};
 127     if(args.size() > 1 && args[0] == "-device")
 128     {
 129         device = DevicePtr{alcOpenDevice(std::string{args[1]}.c_str())};
 130         if(!device)
 131             fmt::println(stderr, "Failed to open \"{}\", trying default", args[1]);
 132         args = args.subspan(2);
 133     }
 134     if(!device)
 135         device = DevicePtr{alcOpenDevice(nullptr)};
 136     if(!device)
 137     {
 138         fmt::println(stderr, "Could not open a device!");
 139         return 1;
 140     }
 141
 142     if(!alcIsExtensionPresent(device.get(), "ALC_EXT_debug"))
 143     {
 144         fmt::println(stderr, "ALC_EXT_debug not supported on device");
 145         return 1;
 146     }
 147
 148     /* Load the Debug API functions we're using. */
 149 #define LOAD_PROC(N) N = reinterpret_cast<decltype(N)>(alcGetProcAddress(device.get(), #N))
 150     LOAD_PROC(alDebugMessageCallbackEXT);
 151     LOAD_PROC(alDebugMessageInsertEXT);
 152     LOAD_PROC(alDebugMessageControlEXT);
 153     LOAD_PROC(alPushDebugGroupEXT);
 154     LOAD_PROC(alPopDebugGroupEXT);
 155     LOAD_PROC(alGetDebugMessageLogEXT);
 156     LOAD_PROC(alObjectLabelEXT);
 157     LOAD_PROC(alGetObjectLabelEXT);
 158     LOAD_PROC(alGetPointerEXT);
 159     LOAD_PROC(alGetPointervEXT);
 160 #undef LOAD_PROC
 161
 162     /* Create a debug context and set it as current. If -nodebug was specified,
 163      * create a non-debug context (to see how debug messages react).
 164      */
 165     auto flags = ALCint{ALC_CONTEXT_DEBUG_BIT_EXT};
 166     if(!args.empty() && args[0] == "-nodebug")
 167         flags &= ~ALC_CONTEXT_DEBUG_BIT_EXT;
 168
 169     const auto attribs = std::array<ALCint,3>{{
 170         ALC_CONTEXT_FLAGS_EXT, flags,
 171         0 /* end-of-list */
 172     }};
 173     auto context = ContextPtr{alcCreateContext(device.get(), attribs.data())};
 174     if(!context || alcMakeContextCurrent(context.get()) == ALC_FALSE)
 175     {
 176         fmt::println(stderr, "Could not create and set a context!");
 177         return 1;
 178     }
 179
 180     /* Enable low-severity debug messages, which are disabled by default. */
 181     alDebugMessageControlEXT(AL_DONT_CARE_EXT, AL_DONT_CARE_EXT, AL_DEBUG_SEVERITY_LOW_EXT, 0,
 182         nullptr, AL_TRUE);
 183
 184     fmt::println("Context flags: 0x{:08x}", alGetInteger(AL_CONTEXT_FLAGS_EXT));
 185
 186     /* A debug context has debug output enabled by default. But in case this
 187      * isn't a debug context, explicitly enable it (probably won't get much, if
 188      * anything, in that case).
 189      */
 190     fmt::println("Default debug state is: {}",
 191         alIsEnabled(AL_DEBUG_OUTPUT_EXT) ? "enabled"sv : "disabled"sv);
 192     alEnable(AL_DEBUG_OUTPUT_EXT);
 193
 194     /* The max debug message length property will allow us to define message
 195      * storage of sufficient length. This includes space for the null
 196      * terminator.
 197      */
 198     const auto maxloglength = alGetInteger(AL_MAX_DEBUG_MESSAGE_LENGTH_EXT);
 199     fmt::println("Max debug message length: {}", maxloglength);
 200
 201     fmt::println("");
 202
 203     /* Doppler Velocity is deprecated since AL 1.1, so this should generate a
 204      * deprecation debug message. We'll first handle debug messages through the
 205      * message log, meaning we'll query for and read it afterward.
 206      */
 207     fmt::println("Calling alDopplerVelocity(0.5f)...");
 208     alDopplerVelocity(0.5f);
 209
 210     for(auto numlogs = alGetInteger(AL_DEBUG_LOGGED_MESSAGES_EXT);numlogs > 0;--numlogs)
 211     {
 212         auto message = std::vector<char>(static_cast<ALuint>(maxloglength), '\0');
 213         auto source = ALenum{};
 214         auto type = ALenum{};
 215         auto id = ALuint{};
 216         auto severity = ALenum{};
 217         auto msglength = ALsizei{};
 218
 219         /* Getting the message removes it from the log. */
 220         const auto read = alGetDebugMessageLogEXT(1, maxloglength, &source, &type, &id, &severity,
 221             &msglength, message.data());
 222         if(read != 1)
 223         {
 224             fmt::println(stderr, "Read {} debug messages, expected to read 1", read);
 225             break;
 226         }
 227
 228         /* The message lengths returned by alGetDebugMessageLogEXT include the
 229          * null terminator, so subtract one for the string_view length. If we
 230          * read more than one message at a time, the length could be used as
 231          * the offset to the next message.
 232          */
 233         const auto msgstr = std::string_view{message.data(),
 234             static_cast<ALuint>(msglength ? msglength-1 : 0)};
 235         fmt::println("Got message from log:\n"
 236             "  Source: {}\n"
 237             "  Type: {}\n"
 238             "  ID: {}\n"
 239             "  Severity: {}\n"
 240             "  Message: \"{}\"", GetDebugSourceName(source), GetDebugTypeName(type), id,
 241             GetDebugSeverityName(severity), msgstr);
 242     }
 243     fmt::println("");
 244
 245     /* Now set up a callback function. This lets us print the debug messages as
 246      * they happen without having to explicitly query and get them.
 247      */
 248     static constexpr auto debug_callback = [](ALenum source, ALenum type, ALuint id,
 249         ALenum severity, ALsizei length, const ALchar *message, void *userParam [[maybe_unused]])
 250         noexcept -> void
 251     {
 252         /* The message length provided to the callback does not include the
 253          * null terminator.
 254          */
 255         const auto msgstr = std::string_view{message, static_cast<ALuint>(length)};
 256         fmt::println("Got message from callback:\n"
 257             "  Source: {}\n"
 258             "  Type: {}\n"
 259             "  ID: {}\n"
 260             "  Severity: {}\n"
 261             "  Message: \"{}\"", GetDebugSourceName(source), GetDebugTypeName(type), id,
 262             GetDebugSeverityName(severity), msgstr);
 263     };
 264     alDebugMessageCallbackEXT(debug_callback, nullptr);
 265
 266     if(const auto numlogs = alGetInteger(AL_DEBUG_LOGGED_MESSAGES_EXT))
 267         fmt::println(stderr, "{} left over logged message{}!", numlogs, (numlogs==1)?"":"s");
 268
 269     /* This should also generate a deprecation debug message, which will now go
 270      * through the callback.
 271      */
 272     fmt::println("Calling alGetInteger(AL_DOPPLER_VELOCITY)...");
 273     auto dv [[maybe_unused]] = alGetInteger(AL_DOPPLER_VELOCITY);
 274     fmt::println("");
 275
 276     /* These functions are notoriously unreliable for their behavior, they will
 277      * likely generate portability debug messages.
 278      */
 279     fmt::println("Calling alcSuspendContext and alcProcessContext...");
 280     alcSuspendContext(context.get());
 281     alcProcessContext(context.get());
 282     fputs("\n", stdout);
 283
 284     fmt::println("Pushing a debug group, making some invalid calls, and popping the debug group...");
 285     alPushDebugGroupEXT(AL_DEBUG_SOURCE_APPLICATION_EXT, 0, -1, "Error test group");
 286     alSpeedOfSound(0.0f);
 287     /* Can't set the label of the null buffer. */
 288     alObjectLabelEXT(AL_BUFFER, 0, -1, "The null buffer");
 289     alPopDebugGroupEXT();
 290     fmt::println("");
 291
 292     /* All done, insert a custom message and unset the callback. The context
 293      * and device will clean themselves up.
 294      */
 295     alDebugMessageInsertEXT(AL_DEBUG_SOURCE_APPLICATION_EXT, AL_DEBUG_TYPE_MARKER_EXT, 0,
 296         AL_DEBUG_SEVERITY_NOTIFICATION_EXT, -1, "End of run, cleaning up");
 297     alDebugMessageCallbackEXT(nullptr, nullptr);
 298
 299     return 0;
 300 }
 301
 302 } // namespace
 303
 304 int main(int argc, char **argv)
 305 {
 306     assert(argc >= 0);
 307     auto args = std::vector<std::string_view>(static_cast<unsigned int>(argc));
 308     std::copy_n(argv, args.size(), args.begin());
 309     return main(al::span{args});
 310 }