{"id":73,"date":"2022-05-05T23:41:05","date_gmt":"2022-05-06T06:41:05","guid":{"rendered":"https:\/\/blogs.oregonstate.edu\/usageoptions\/?p=73"},"modified":"2022-05-05T23:54:49","modified_gmt":"2022-05-06T06:54:49","slug":"using-sdl-part-1","status":"publish","type":"post","link":"https:\/\/blogs.oregonstate.edu\/usageoptions\/2022\/05\/05\/using-sdl-part-1\/","title":{"rendered":"Using SDL Part 1"},"content":{"rendered":"\n<p style=\"font-size:1rem\">This post introduces useful functions, structures, and constants in the <a href=\"https:\/\/wiki.libsdl.org\/APIByCategory\">SDL 2.0 API<\/a>. It covers basic details such as return values and parameters of functions and names and data types of members of structs. For more detailed info, visit the links in the references.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" style=\"font-size:1.75rem;text-transform:capitalize\">Initialization<\/h3>\n\n\n\n<p style=\"font-size:1rem\">To use SDL 2.0 in your program, call the <code>SDL_Init()<\/code> function.<a href=\"#ref\"><sup>[1]<\/sup><\/a><\/p>\n\n\n\n<pre class=\"wp-block-code has-light-gray-background-color has-background\" style=\"font-size:1rem\"><code>int SDL_Init(Uint32 flags);\n\n<strong>Returns:<\/strong> 0 if successful or a negative error code if unsuccessful <\/code><\/pre>\n\n\n\n<p style=\"font-size:1rem\">The <code>flags<\/code> parameter specifies which subsystems should be initialized. It can be one or more of the following:<\/p>\n\n\n\n<ul class=\"wp-block-list\" style=\"font-size:1rem\"><li>SDL_INIT_TIMER: timer subsystem<\/li><li>SDL_INIT_AUDIO: audio subsystem<\/li><li>SDL_INIT_VIDEO: video subsystem; automatically initializes the events subsystem<\/li><li>SDL_INIT_JOYSTICK: joystick subsystem; automatically initializes the events subsystem<\/li><li>SDL_INIT_HAPTIC: haptic (force feedback) subsystem<\/li><li>SDL_INIT_GAMECONTROLLER: controller subsystem; automatically initializes the joystick subsystem<\/li><li>SDL_INIT_EVENTS: events subsystem<\/li><li>SDL_INIT_EVERYTHING: all of the above subsystems<\/li><li>SDL_INIT_NOPARACHUTE: compatibility; this flag is ignored<\/li><\/ul>\n\n\n\n<p style=\"font-size:1rem\">Use a logical OR to use more than one flag, e.g.,<\/p>\n\n\n\n<pre class=\"wp-block-code has-light-gray-background-color has-background\" style=\"font-size:1rem\"><code>SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO);<\/code><\/pre>\n\n\n\n<p style=\"font-size:1rem\">There is another function called <code>SDL_InitSubSystem()<\/code> that is identical to <code>SDL_Init()<\/code> in all but the name of the function.<a href=\"#ref\"><sup>[2]<\/sup><\/a><\/p>\n\n\n\n<h3 class=\"wp-block-heading\" style=\"font-size:1.75rem;text-transform:capitalize\">Shutdown Cleanup<\/h3>\n\n\n\n<p style=\"font-size:1rem\">Call the <code>SDL_Quit()<\/code> function to perform final cleanup of all initialized subsystems.<\/p>\n\n\n\n<pre class=\"wp-block-code has-light-gray-background-color has-background\"><code>void SDL_Quit(void);<\/code><\/pre>\n\n\n\n<p style=\"font-size:1rem\">This function can be used with <code><a href=\"https:\/\/man7.org\/linux\/man-pages\/man3\/atexit.3.html\">atexit()<\/a><\/code> to ensure that it is called when your program shuts down.<sup><a href=\"#ref\">[3]<\/a><\/sup><\/p>\n\n\n\n<pre class=\"wp-block-code has-light-gray-background-color has-background\"><code>atexit(SDL_Quit);<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\" style=\"font-size:1.75rem;text-transform:capitalize\">Error Handling<\/h3>\n\n\n\n<h4 class=\"wp-block-heading\" style=\"font-size:1.25rem\">SDL_GetError()<\/h4>\n\n\n\n<p style=\"font-size:1rem\"><code>SDL_GetError()<\/code> gets a message about the last error on the current thread and returns it as a string.<sup><a href=\"#ref\">[4]<\/a><\/sup><\/p>\n\n\n\n<pre class=\"wp-block-code has-light-gray-background-color has-background\"><code>const char* SDL_GetError(void);\n\n<strong>Returns:<\/strong> a string with information about the last error, or an empty string if there hasn't been an error since the last call to SDL_ClearError()<\/code><\/pre>\n\n\n\n<p style=\"font-size:1rem\"><code>SDL_GetError()<\/code> should be called if an SDL function signals that an error occurred. It should not be used to determine whether an error occurred since some SDL functions will set an error string even when successful.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\" style=\"font-size:1.25rem\">SDL_ClearError()<\/h4>\n\n\n\n<p style=\"font-size:1rem\"><code>SDL_ClearError()<\/code> clears the error message for the current thread.<sup><a href=\"#ref\">[5]<\/a><\/sup><\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">void SDL_ClearError(void);<\/pre>\n\n\n\n<h4 class=\"wp-block-heading\" style=\"font-size:1.25rem\">SDL_SetError()<\/h4>\n\n\n\n<p style=\"font-size:1rem\"><code>SDL_SetError()<\/code> sets the SDL error message for the current thread. Its arguments work similarly to <a href=\"https:\/\/man7.org\/linux\/man-pages\/man3\/printf.3.html\">printf()<\/a>.<sup><a href=\"#ref\">[6]<\/a><\/sup><\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">int SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fmt, \u2026);\n\n<strong>Returns:<\/strong> always returns -1<\/pre>\n\n\n\n<p style=\"font-size:1rem\"><code>fmt<\/code> is the desired error message. It is a printf-style format string.<\/p>\n\n\n\n<p style=\"font-size:1rem\"><code>...<\/code> means that there can be any number of additional parameters matching % tokens in the <code>fmt<\/code> string.<\/p>\n\n\n\n<p style=\"font-size:1rem\">Example code:<\/p>\n\n\n\n<pre class=\"wp-block-code has-light-gray-background-color has-background\"><code><a href=\"#ref\">&#091;6]<\/a>\nif (error_code) {\n    return SDL_SetError(\"This operation has failed: %d\", error_code);\n}<\/code><\/pre>\n\n\n\n<h3 class=\"wp-block-heading\" style=\"font-size:1.75rem;text-transform:capitalize\">Creating and Destroying Windows<\/h3>\n\n\n\n<h4 class=\"wp-block-heading\" style=\"font-size:1.25rem\">SDL_CreateWindow()<\/h4>\n\n\n\n<p style=\"font-size:1rem\"><code>SDL_CreateWindow()<\/code> create<code>DL_CreateWindow()<\/code>s a new window with the given title, size, and position.<sup><a href=\"#ref\">[7]<\/a><\/sup><\/p>\n\n\n\n<pre class=\"wp-block-code has-light-gray-background-color has-background\"><code>SDL_Window *SDL_CreateWindow(const char *title,\nint x, int y, int w,\nint h, Uint32 flags);\n\n<strong>Returns:<\/strong> on success, a pointer to the new window instance created; on failure, NULL<\/code><\/pre>\n\n\n\n<p style=\"font-size:1rem\"><code>title<\/code> is a string that will be the title of the window.<br><code>x<\/code> is the x position of the window, <code>SDL_WINDOWPOS_CENTERED<\/code>, or <code>SDL_WINDOWPOS_UNDEFINED<\/code>.<br><code>y<\/code> is the y position of the window, <code>SDL_WINDOWPOS_CENTERED<\/code>, or <code>SDL_WINDOWPOS_UNDEFINED<\/code>.<br><code>w<\/code> is the width of the window in screen coordinates.<br><code>h<\/code> is the height of the window in screen coordinates.<br><code>flags<\/code> is either 0 or one or more of the following <code>SDL_WindowFlags<\/code> OR&#8217;d together:<\/p>\n\n\n\n<p style=\"font-size:1rem\">SDL_WINDOW_FULLSCREEN: fullscreen window<br>SDL_WINDOW_FULLSCREEN_DESKTOP: fullscreen window at desktop resolution<br>SDL_WINDOW_OPENGL: window usable with an OpenGL context<br>SDL_WINDOW_VULKAN: window usable with a Vulkan instance<br>SDL_WINDOW_METAL: window usable with a Metal instance<br>SDL_WINDOW_HIDDEN: window is not visible<br>SDL_WINDOW_BORDERLESS: no window decoration<br>SDL_WINDOW_RESIZABLE: window can be resized<br>SDL_WINDOW_MINIMIZED: window is minimized<br>SDL_WINDOW_MAXIMIZED: window is maximized<br>SDL_WINDOW_INPUT_GRABBED: window has grabbed input focus<br>SDL_WINDOW_ALLOW_HIGHDPI: window should be created in high-DPI mode if supported (&gt;= SDL 2.0.1)<\/p>\n\n\n\n<h4 class=\"wp-block-heading\" style=\"font-size:1.25rem\">SDL_DestroyWindow<\/h4>\n\n\n\n<p style=\"font-size:1rem\"><code>SDL_DestroyWindow()<\/code> destroys the given window instance.<sup><a href=\"#ref\">[8]<\/a><\/sup><\/p>\n\n\n\n<pre class=\"wp-block-code has-light-gray-background-color has-background\"><code>void SDL_DestroyWindow(SDL_Window *window);<\/code><\/pre>\n\n\n\n<p style=\"font-size:1rem\"><code>window<\/code> is the window to destroy. If window is NULL, the SDL error message will be set.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\" style=\"font-size:1.25rem\">Getters and Setters<\/h4>\n\n\n\n<p style=\"font-size:1rem\">You can associate a name and other data with a <code>window<\/code> instance using <code>SDL_SetWindowData()<\/code>.<sup><a href=\"#ref\">[9]<\/a><\/sup><\/p>\n\n\n\n<pre class=\"wp-block-code has-light-gray-background-color has-background\"><code>void* SDL_SetWindowData(SDL_Window *window,\nconst char *name,\nvoid *userdata);\n\n<strong>Returns:<\/strong> the previous data associated with name<\/code><\/pre>\n\n\n\n<p style=\"font-size:1rem\"><code>window<\/code> is the window to associate with the pointer to the data.<br><code>name<\/code> is the name of the pointer to the data.<br><code>userdata<\/code> is the associated pointer to the data.<\/p>\n\n\n\n<p style=\"font-size:1rem\">You can then retrieve that data using <code>SDL_GetWindowData()<\/code>.<sup><a href=\"#ref\">[10]<\/a><\/sup><\/p>\n\n\n\n<pre class=\"wp-block-code has-light-gray-background-color has-background\"><code>void* SDL_GetWindowData(SDL_Window *window,\nconst char *name);\n\n<strong>Returns:<\/strong> the data associated with name<\/code><\/pre>\n\n\n\n<p style=\"font-size:1rem\"><code>window<\/code> is the window to query.<br><code>name<\/code> is the name of the pointer to the data.<\/p>\n\n\n\n<p style=\"font-size:1rem\">Each window instance has an ID associated with it, which is used by <a href=\"https:\/\/wiki.libsdl.org\/SDL_WindowEvent\"><code>SDL_WindowEvent<\/code><\/a> structure. To work with that structure, it is often necessary to be able to convert from a window instance to its ID and vice versa. Fortunately, there are functions to facilitate both conversions.<\/p>\n\n\n\n<p style=\"font-size:1rem\"><code>SDL_GetWindowID()<\/code> retrieves the ID of the given <code>window<\/code>.<sup><a href=\"#ref\">[11]<\/a><\/sup><\/p>\n\n\n\n<pre class=\"wp-block-code has-light-gray-background-color has-background\"><code>Uint32 SDL_GetWindowID(SDL_Window *window);\n\n<strong>Returns:<\/strong> the ID of the window on success or 0 on failure<\/code><\/pre>\n\n\n\n<p style=\"font-size:1rem\"><code>window<\/code> is the window to query.<\/p>\n\n\n\n<p style=\"font-size:1rem\"><code>SDL_GetWindowFromID()<\/code> retrieves the <code>window<\/code> instance with the given ID.<sup><a href=\"#ref\">[12]<\/a><\/sup><\/p>\n\n\n\n<pre class=\"wp-block-code has-light-gray-background-color has-background\"><code>SDL_Window *SDL_GetWindowFromID(Uint32 id);\n\n<strong>Returns:<\/strong> the window associated with id or NULL if it doesn't exist<\/code><\/pre>\n\n\n\n<p style=\"font-size:1rem\"><code>id<\/code> is the ID of the window.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\" style=\"font-size:1.75rem;text-transform:capitalize\">References<\/h3>\n\n\n\n<ol class=\"wp-block-list\" id=\"ref\" style=\"font-size:1rem\"><li><a href=\"https:\/\/wiki.libsdl.org\/SDL_Init\">https:\/\/wiki.libsdl.org\/SDL_Init<\/a><\/li><li><a href=\"https:\/\/wiki.libsdl.org\/SDL_InitSubSystem\">https:\/\/wiki.libsdl.org\/SDL_InitSubSystem<\/a><\/li><li><a href=\"https:\/\/wiki.libsdl.org\/SDL_Quit\">https:\/\/wiki.libsdl.org\/SDL_Quit<\/a><\/li><li><a href=\"https:\/\/wiki.libsdl.org\/SDL_GetError\">https:\/\/wiki.libsdl.org\/SDL_GetError<\/a><\/li><li><a href=\"https:\/\/wiki.libsdl.org\/SDL_ClearError\">https:\/\/wiki.libsdl.org\/SDL_ClearError<\/a><\/li><li><a href=\"https:\/\/wiki.libsdl.org\/SDL_SetError\">https:\/\/wiki.libsdl.org\/SDL_SetError<\/a><\/li><li><a href=\"https:\/\/wiki.libsdl.org\/SDL_CreateWindow\">https:\/\/wiki.libsdl.org\/SDL_CreateWindow<\/a><\/li><li><a href=\"https:\/\/wiki.libsdl.org\/SDL_DestroyWindow\">https:\/\/wiki.libsdl.org\/SDL_DestroyWindow<\/a><\/li><li><a href=\"https:\/\/wiki.libsdl.org\/SDL_SetWindowData\">https:\/\/wiki.libsdl.org\/SDL_SetWindowData<\/a><\/li><li><a href=\"https:\/\/wiki.libsdl.org\/SDL_GetWindowData\">https:\/\/wiki.libsdl.org\/SDL_GetWindowData<\/a><\/li><li><a href=\"https:\/\/wiki.libsdl.org\/SDL_GetWindowID\">https:\/\/wiki.libsdl.org\/SDL_GetWindowID<\/a><\/li><li><a href=\"https:\/\/wiki.libsdl.org\/SDL_GetWindowFromID\">https:\/\/wiki.libsdl.org\/SDL_GetWindowFromID<\/a><\/li><\/ol>\n\n\n\n<p style=\"font-size:1rem\">Stay tuned for part 2.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>This post introduces useful functions, structures, and constants in the SDL 2.0 API. It covers basic details such as return values and parameters of functions and names and data types of members of structs. For more detailed info, visit the &hellip; <a href=\"https:\/\/blogs.oregonstate.edu\/usageoptions\/2022\/05\/05\/using-sdl-part-1\/\">Continue reading <span class=\"meta-nav\">&rarr;<\/span><\/a><\/p>\n","protected":false},"author":12377,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[13,10,1],"tags":[17,21,20,22],"class_list":["post-73","post","type-post","status-publish","format-standard","hentry","category-emulators","category-life","category-uncategorized","tag-c","tag-capstone-project","tag-school","tag-sdl"],"_links":{"self":[{"href":"https:\/\/blogs.oregonstate.edu\/usageoptions\/wp-json\/wp\/v2\/posts\/73","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blogs.oregonstate.edu\/usageoptions\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.oregonstate.edu\/usageoptions\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.oregonstate.edu\/usageoptions\/wp-json\/wp\/v2\/users\/12377"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.oregonstate.edu\/usageoptions\/wp-json\/wp\/v2\/comments?post=73"}],"version-history":[{"count":11,"href":"https:\/\/blogs.oregonstate.edu\/usageoptions\/wp-json\/wp\/v2\/posts\/73\/revisions"}],"predecessor-version":[{"id":85,"href":"https:\/\/blogs.oregonstate.edu\/usageoptions\/wp-json\/wp\/v2\/posts\/73\/revisions\/85"}],"wp:attachment":[{"href":"https:\/\/blogs.oregonstate.edu\/usageoptions\/wp-json\/wp\/v2\/media?parent=73"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.oregonstate.edu\/usageoptions\/wp-json\/wp\/v2\/categories?post=73"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.oregonstate.edu\/usageoptions\/wp-json\/wp\/v2\/tags?post=73"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}