SDL: Added INTRO-emscripten.md

SDLPushPostBot · January 14, 2025, 12:44am

From 0eaa8c6d81a693c1ef57bc27ae4fac03c40735b9 Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Mon, 13 Jan 2025 15:49:47 -0800
Subject: [PATCH] Added INTRO-emscripten.md

---
 docs/INTRO-emscripten.md  | 38 +++++++++++++++++++
 docs/README-emscripten.md |  6 +--
 docs/hello.c              | 80 +++++++++++++++++++++------------------
 3 files changed, 85 insertions(+), 39 deletions(-)
 create mode 100644 docs/INTRO-emscripten.md

diff --git a/docs/INTRO-emscripten.md b/docs/INTRO-emscripten.md
new file mode 100644
index 0000000000000..89831248cc823
--- /dev/null
+++ b/docs/INTRO-emscripten.md
@@ -0,0 +1,38 @@
+
+# Introduction to SDL with Emscripten
+
+First, you should have the Emscripten SDK installed from:
+
+https://emscripten.org/docs/getting_started/downloads.html
+
+We'll start by creating a simple project to build and run [hello.c](hello.c)
+
+## Building SDL
+
+Once you have a command line interface with the Emscripten SDK set up and you've changed directory to the SDL directory, you can build SDL like this:
+
+```sh
+mkdir hello
+cd hello
+emcmake cmake ..
+emmake make
+```
+
+## Building your app
+
+In this case we'll just run a simple command to compile our source with the SDL library we just built:
+```sh
+emcc -o index.html ../docs/hello.c -I../include -L. -lSDL3
+```
+
+## Running your app
+
+You can now run your app by pointing a webserver at your build directory and connecting a web browser to it.
+
+## More information
+
+A more complete example is available at:
+
+https://github.com/Ravbug/sdl3-sample
+
+Additional information and troubleshooting is available in [README-emscripten.md](README-emscripten.md)
diff --git a/docs/README-emscripten.md b/docs/README-emscripten.md
index 6bf1cacca8e86..2b8146893a94a 100644
--- a/docs/README-emscripten.md
+++ b/docs/README-emscripten.md
@@ -239,13 +239,13 @@ If you want to build with thread support, something like this works:
 ```bash
 mkdir build
 cd build
-emcmake cmake -DSDL_THREADS=On ..
+emcmake cmake -DSDL_THREADS=ON ..
 # you can also do `emcmake cmake -G Ninja ..` and then use `ninja` instead of this command.
 emmake make -j4

-To build the tests, add -DSDL_TESTS=On to the emcmake cmake command line.
-To build the examples, add -DSDL_EXAMPLES=On to the emcmake cmake command line.
+To build the tests, add -DSDL_TESTS=ON to the emcmake cmake command line.
+To build the examples, add -DSDL_EXAMPLES=ON to the emcmake cmake command line.

Building your app

diff --git a/docs/hello.c b/docs/hello.c
index f513d9318abc0…74a04bc246aa1 100644
— a/docs/hello.c
+++ b/docs/hello.c
@@ -9,52 +9,60 @@
including commercial applications, and to alter it and redistribute it
freely.
/
+#define SDL_MAIN_USE_CALLBACKS 1 / use the callbacks instead of main() */
#include <SDL3/SDL.h>
#include <SDL3/SDL_main.h>

-int main(int argc, char *argv)
+static SDL_Window *window = NULL;
+static SDL_Renderer renderer = NULL;
+
+/ This function runs once at startup. */
+SDL_AppResult SDL_AppInit(void **appstate, int argc, char *argv)
+{

/* Create the window */
if (!SDL_CreateWindowAndRenderer(“Hello World”, 800, 600, SDL_WINDOW_FULLSCREEN, &window, &renderer)) {

   SDL_Log("Couldn't create window and renderer: %s\n", SDL_GetError());

```
   return SDL_APP_FAILURE;
```
}
return SDL_APP_CONTINUE;
+}

+/* This function runs when a new event (mouse input, keypresses, etc) occurs. */
+SDL_AppResult SDL_AppEvent(void *appstate, SDL_Event *event)
+{

if (event->type == SDL_EVENT_KEY_DOWN ||
```
   event->type == SDL_EVENT_QUIT) {
```

   return SDL_APP_SUCCESS;  /* end the program, reporting success to the OS. */

}
return SDL_APP_CONTINUE;
+}

+/* This function runs once per frame, and is the heart of the program. */
+SDL_AppResult SDL_AppIterate(void *appstate)
{

SDL_Window *window = NULL;
SDL_Renderer *renderer = NULL;
const char *message = “Hello World!”;
int w = 0, h = 0;
float x, y;
const float scale = 4.0f;
bool done = false;
/* Create the window */
if (!SDL_CreateWindowAndRenderer(“Hello World”, 0, 0, SDL_WINDOW_FULLSCREEN, &window, &renderer)) {

   SDL_Log("Couldn't create window and renderer: %s\n", SDL_GetError());

```
   return 1;
```
}

/* Center the message and scale it up */
SDL_GetRenderOutputSize(renderer, &w, &h);
SDL_SetRenderScale(renderer, scale, scale);
x = ((w / scale) - SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE * SDL_strlen(message)) / 2;
y = ((h / scale) - SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE) / 2;

while (!done) {
```
   SDL_Event event;
```
```
   /* Handle events */
```
```
   while (SDL_PollEvent(&event)) {
```

       if (event.type == SDL_EVENT_KEY_DOWN ||

           event.type == SDL_EVENT_MOUSE_BUTTON_DOWN ||

           event.type == SDL_EVENT_QUIT) {

```
           done = true;
```
```
       }
```
```
   }
```

   /* Center the message and scale it up */

   SDL_GetRenderOutputSize(renderer, &w, &h);

   SDL_SetRenderScale(renderer, scale, scale);

   x = ((w / scale) - SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE * SDL_strlen(message)) / 2;

   y = ((h / scale) - SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE) / 2;

```
   /* Draw the message */
```

   SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);

```
   SDL_RenderClear(renderer);
```

   SDL_SetRenderDrawColor(renderer, 255, 255, 255, 255);

   SDL_RenderDebugText(renderer, x, y, message);

```
   SDL_RenderPresent(renderer);
```
}
SDL_Quit();

/* Draw the message */
SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);
SDL_RenderClear(renderer);
SDL_SetRenderDrawColor(renderer, 255, 255, 255, 255);
SDL_RenderDebugText(renderer, x, y, message);
SDL_RenderPresent(renderer);
return SDL_APP_CONTINUE;
+}

return 0;
+/* This function runs once at shutdown. */
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
+{
}