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