Window and Clearing

• SDL_CreateWindow
  • One of the most common functions when you use SDL, along with SDL_Init, it's probably closest to the function that "every" SDL application calls. There's a fair bit of flexibility in Window creation, and we won't cover most of it as it's not particularly relevant to rendering.
• SDL_CreateWindowWithProperties
  • Technically we only alluded to this, we'll almost certainly discuss this or functions like it later. Essentially these substitute the arguments of the function with an SDL_Properties object, to allow functions to be extended in the future without needing to create entirely new symbols.
• SDL_DestroyWindow
  • Simply the converse of SDL_CreateWindow, it just brings the Window and related resources down.
• The Events Subsystem
  • We'll go over this in more detail as needed, but it wouldn't hurt to look over the docs here to get an idea on the general concepts here and how it works beyond my blurbs.
• SDL_PollEvent
  • One of several methods of retrieving events from the operating system. Typically today we'd be using the callbacks system and never need to use SDL_PollEvent or one of the related functions.
  • This function and related functions have some deficiencies due to how some Operating Systems deal with some user facing operations. The callbacks system resolves this, but there are ways to handle them here as well. It'll be covered in a later chapter, but for now if you notice odd behavior with resizing the window (which we haven't even enabled yet), or moving the window, just know that this is expected.
• SDL_Event, SDL_CommonEvent, SDL_EVENT_QUIT of SDL_EventType, and it's struct SDL_QuitEvent
  • SDL_Event is a union of structs SDL uses to pass us every event that it wants to inform us about. It contains within it every event struct, and we can differentiate between them by examining the type field within the SDL_CommonEvent and checking it against the enums from SDL_EventType. In this case, we just wanted to know when the user was requesting us to quit, which is fired when the user asks to close the last window as one example.
  • (Boring Technical Detail) For completeness sake, SDL_Event also directly contains a type field you can inspect to know the type. That said, for incredibly boring and technical details, in C++ specifically using this field to know which union member to use is undefined behavior. So I avoid doing so, even though in practice, every compiler I'm aware of treats this case as-if it were C and thus works as expected.

• SDL_CreateGPUDevice
  • This is another one of those "every SDL_GPU application will need to call this" functions. It does all of the GPU initialization for us. It selects an API, selects a GPU, sets up validation layers, and more. I covered above what the args are for this, they're pretty simple. So I'd also recommend taking a look at the 'properties you can pass in to that version of the function.' There's of course the args that we can set in the normal function, but also preferences for the type of GPU to select, and a few backend specific properties. The Vulkan ones in particular are helpful by giving up some features for a drastic increase in Android support.
  • I wanted to cover creating some small abstractions and objects for management early. I think it's important to have these primitives to help write our applications, and I don't want to write tutorials that pretend to do everything in main. That said, I'll try to ensure they always stick to one file! (Plus the shader files.)
• SDL_DestroyGpuDevice
  • This will destroy all the GPU resources you've created, whatever SDL_GPU has created in the background, and free the device. It's not safe to use anything you've created with the GPU Device after you've called this.
• SDL_zero
  • This is a macro that lets us set a value to 0. This is really helpful when writing SDL_GPU code, the vast majority of functions take structs to configure them, and the majority of those have very reasonable default values if all their fields are set to 0. Since we're not using C designated initializer or some sort of template in C++, we use this macro to zero out these structs whenever we make one.
• SDL_ClaimWindowForGPUDevice
  • This pretty much does as it says on the tin. Generally speaking, it's a rule that only one graphics API can really own a Window at a time. Things can get a bit complicated with offscreen rendering, multiple APIs, and shared resources, but we're not anywhere near that yet, and may never be.
• SDL_GetGPUShaderFormats
  • Fundamentally all this is really doing for us is telling us, which shaders to pass in when we call 'SDL_CreateGPUShader' later on.
• SDL_CreateProperties
  • There are many reasons you might create a and use a properties object. Maybe you want to use it as a map of sorts. In this case, we're going to be passing this into functions and Create structs when creating GPU resources. Almost every GPU resource can be named, and this will be helpful when getting debug output from the Vulkan Validation layers, and the DX12 debug output.
  • As for why we're creating it and storing it. I just feel it's wasteful to create one every time we make a GPU resource. We could run into trouble with this if we selectively set properties on say one 'SDL_CreateGPUTexture' call and then leave them set for our next call into the same function. We'll avoid that when we write our wrapper functions by allowing us to pass in a custom Properties object as well.
• SDL_DestroyProperties
  • This frees up all the resources SDL created internally to handle this Properties object. Don't try to use it again after calling this!

• SDL_AcquireGPUCommandBuffer
  • A common thing we hear about in Graphics is about doing things on other threads, such as recording command buffers. In practice, this isn't really all that slow, or at least the recording part isn't, perhaps walking your scene might be but that's an architectural issue. That said, I won't say there's no uses of threads here. In my experience, it can be very useful to do mid-frame uploads when you do things like load assets. The upload itself usually isn't the slow part, but it can be easier to do the upload on another thread if you're already doing the unpacking on another thread. We might look into these strategies in a later chapter if I can find a compelling use case that doesn't take a lot of non-GPU work.
• SDL_SubmitGPUCommandBuffer
  • Not much to say here, but if you're looking into threading, it may well be that you'll want to look into the sibling function SDL_SubmitGPUCommandBufferAndAcquireFence, which lets you get a fence to wait on if you need a command buffer to complete before proceeding, such as when doing a read of GPU memory from the CPU side.
• SDL_WaitAndAcquireGPUSwapchainTexture
  • There's not too much to say here, this is how we ask for a Swapchain to manipulate in our passes.
  • Some other APIs related to Swapchains that I alluded to above for further reading if you want to look ahead or the tutorial hasn't covered them yet:
    • 'SDL_AcquireGPUSwapchainTexture'
      • No waiting for the swapchain, but also, you might not have one available.
    • 'SDL_SetGPUAllowedFramesInFlight'
      • Reduce or increase the number of frames in flight. This generally affects latency, with lower being lower, but increasing the likely hood of idling.
    • 'SDL_SetGPUSwapchainParameters'
      • Change the format of the Texture, as well as the presentation mode. Changing the format is useful when you want to render an HDR image, changing the present mode would allow you to turn off VSYNC and switch to allowing screen tearing or mailbox where you can keep submitting and the GPU will use the latest image given when it's time to display. Both of these need to be queried for support before changing.
• SDL_GPUColorTargetInfo
  • I covered the immediately relevant properties above, but there's a fair bit of stuff you can adjust here, such as a resolve texture for doing various multi-sampling techniques. We'll try to explore this functionality in a later chapter at some point.
• SDL_BeginGPURenderPass
  • Nothing additional to point out about this, there's depth textures, but we'll go over it later on, perhaps in a sprite batching chapter.
• SDL_EndGPURenderPass
  • As simple as it gets, this ends the Render Pass you were adding commands to. It should be noted that it's not unlikely you'll have several of these in a frame, though obviously you don't want to go overboard. As you may suspect, you'll need to End a Render Pass and Begin a new one if you have to change the Textures you're rendering to. One example may be a blur shader, where you need to read from a target you did your initial geometry rendering to, render to an intermediate Texture for a horizontal blur, and finally render to a final Texture using a vertical blur pass.

#include <SDL3/SDL.h>

// This is for testing to ensure the code works in both C and C++,
// this entire preprocessor block should just be the #include
// in your own code.
#ifndef __cplusplus
#include <SDL3/SDL_main.h>
#else
namespace cpp_test {
#endif

/////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Shared GPU Code
/////////////////////////////////////////////////////////////////////////////////////////////////////////////////
typedef struct GpuContext {
  SDL_Window* mWindow;
  SDL_GPUDevice* mDevice;
  SDL_PropertiesID mProperties;
  const char* mShaderEntryPoint;
  SDL_GPUShaderFormat mChosenBackendFormat;
  const char* mChosenBackendFormatExtension;
} GpuContext;

GpuContext gContext;

void CreateGpuContext(SDL_Window* aWindow) {
  SDL_zero(gContext);

  gContext.mWindow = aWindow;
  gContext.mDevice = SDL_CreateGPUDevice(SDL_GPU_SHADERFORMAT_SPIRV | SDL_GPU_SHADERFORMAT_DXIL | SDL_GPU_SHADERFORMAT_MSL, true, NULL);
  SDL_assert(gContext.mDevice);

  SDL_assert(SDL_ClaimWindowForGPUDevice(gContext.mDevice, gContext.mWindow));

  gContext.mProperties = SDL_CreateProperties();
  SDL_assert(gContext.mProperties);

  SDL_GPUShaderFormat availableFormats = SDL_GetGPUShaderFormats(gContext.mDevice);
  gContext.mShaderEntryPoint = NULL;

  if (availableFormats & SDL_GPU_SHADERFORMAT_SPIRV)
  {
    gContext.mChosenBackendFormat = SDL_GPU_SHADERFORMAT_SPIRV;
    gContext.mShaderEntryPoint = "main";
    gContext.mChosenBackendFormatExtension = "spv";
  }
  else if (availableFormats & SDL_GPU_SHADERFORMAT_MSL)
  {
    gContext.mChosenBackendFormat = SDL_GPU_SHADERFORMAT_MSL;
    gContext.mShaderEntryPoint = "main0";
    gContext.mChosenBackendFormatExtension = "msl";
  }
  else if (availableFormats & SDL_GPU_SHADERFORMAT_DXIL)
  {
    gContext.mChosenBackendFormat = SDL_GPU_SHADERFORMAT_DXIL;
    gContext.mShaderEntryPoint = "main";
    gContext.mChosenBackendFormatExtension = "dxil";
  }
}

void DestroyGpuContext() {
  SDL_DestroyProperties(gContext.mProperties);
  SDL_DestroyGPUDevice(gContext.mDevice);
  SDL_DestroyWindow(gContext.mWindow);
  SDL_zero(gContext);
}

/////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Main
/////////////////////////////////////////////////////////////////////////////////////////////////////////////////
int main(int argc, char** argv)
{
  if (!SDL_Init(SDL_INIT_VIDEO)) {
    SDL_Log("Couldn't initialize SDL: %s", SDL_GetError());
    return 1;
  (void)argc;
  (void)argv;
  SDL_assert(SDL_Init(SDL_INIT_VIDEO));

  SDL_Window* window = SDL_CreateWindow(TARGET_NAME, 1280, 720, 0);
  SDL_assert(window);

  CreateGpuContext(window);

  bool running = true;

  while (running) {
    SDL_Event event;
    while (SDL_PollEvent(&event)) {
      switch (event.common.type) {
        case SDL_EVENT_QUIT:
          running = false;
          break;
      }
    }

    SDL_GPUCommandBuffer* commandBuffer = SDL_AcquireGPUCommandBuffer(gContext.mDevice);
    if (!commandBuffer)
    {
      SDL_Log("AcquireGPUCommandBuffer failed: %s", SDL_GetError());
      continue;
    }

    SDL_GPUTexture* swapchainTexture;
    if (!SDL_WaitAndAcquireGPUSwapchainTexture(commandBuffer, gContext.mWindow, &swapchainTexture, NULL, NULL))
    {
      SDL_Log("WaitAndAcquireGPUSwapchainTexture failed: %s", SDL_GetError());
      continue;
    }

    SDL_GPUColorTargetInfo colorTargetInfo;
    SDL_zero(colorTargetInfo);

    colorTargetInfo.texture = swapchainTexture;
    colorTargetInfo.load_op = SDL_GPU_LOADOP_CLEAR;
    colorTargetInfo.store_op = SDL_GPU_STOREOP_STORE;
    colorTargetInfo.clear_color.r = 0.2f;
    colorTargetInfo.clear_color.g = 0.2f;
    colorTargetInfo.clear_color.b = 0.85f;
    colorTargetInfo.clear_color.a = 1.0f;

    SDL_GPURenderPass* renderPass = SDL_BeginGPURenderPass(
      commandBuffer,
      &colorTargetInfo,
      1,
      NULL
    );

    SDL_EndGPURenderPass(renderPass);
    SDL_SubmitGPUCommandBuffer(commandBuffer);
  }

  SDL_Log("Everything is working.");
  DestroyGpuContext();

  SDL_Quit();
  return 0;
}

#ifdef __cplusplus
} // end cpp_test
#endif