iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
👾

Getting Started with raylib

に公開
WebAssembly
C
raylib
tech

raylib

"A simple and easy-to-use library to enjoy videogames programming"
I tried out raylib!
Since it also supports WebAssembly, I tried running a sample app as both a desktop app (mac) and a web app, and experimented with basic shape rendering.

Environment

$ sw_vers
ProductName:	macOS
ProductVersion:	12.4
BuildVersion:	21F79

raylib architecture

It seems raylib consists of the following 7 modules:

  1. rcore: Module for managing Window / Graphic Context / Inputs
  2. rlgl: Module providing an interface that wraps the OpenGL API
  3. rtextures: Module for loading and managing textures/images
  4. rtext: Module for loading font data and rendering text
  5. rshapes: Module for basic 2D rendering
  6. rmodels: Module for loading and rendering 3D models
  7. raudio: Module for managing audio devices and loading/playing sound/music

In addition to the 7 main modules, the following sub-modules also exist:

  1. raymath: Math-related module for Vector2, Vector3, Matrix, Quaternion, etc.
  2. rcamera: Camera-related module for 3D space
  3. rgestures: Module for detecting and processing touch gestures
  4. raygui: A simple IMGUI system module with several controls for tool development
  5. easigns: Animation Easing functionality module based on this

I'm impressed by how comprehensive it is, covering text rendering, 3D, IMGUI, and more ✨

Environment Setup

Since raylib can be installed via Homebrew, I'll go ahead and install it.

$ brew install raylib

Working on macOS · raysan5/raylib Wiki

Running the Sample

raysan5/raylib-game-template: A small template to start your raylib game

I'll clone the repository above and run the following.

$ cd raylib-game-template/src
$ make

You might see some warnings, but it's fine as long as raylib_game is created.
Running it should bring up a window like this:

$ ./raylib_game

Compiling and Running with WebAssembly

Next, I'll try exporting raylib to WebAssembly and displaying it in a web browser.
I'll follow the tutorial here:
Working for Web (HTML5) · raysan5/raylib Wiki

1. Install emscripten toolchain

For the web version, raylib uses Emscripten to compile into WebAssembly.
I'll start by installing Emscripten.
emscripten-core/emsdk: Emscripten SDK

※ Prerequisites for macOS:
Download and install — Emscripten 3.1.19-git (dev) documentation

- macOS 10.14 Mojave or later required
- The following must be installed:
    - Xcode Command Line Tools
    - git
    - cmake
Installation Procedure
$ git clone https://github.com/emscripten-core/emsdk.git
$ cd emsdk
$ ./emsdk install latest
$ ./emsdk activate latest
$ source ./emsdk_env.sh

While running these commands, I encountered the following error during the build in my environment.

Error: Downloading URL 'https://storage.googleapis.com/webassembly/emscripten-releases-builds/deps/node-v14.18.2-darwin-x64.tar.gz': <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1091)>
Warning: Possibly SSL/TLS issue. Update or install Python SSL root certificates (2048-bit or greater) supplied in Python folder or https://pypi.org/project/certifi/ and try again.
error: installation failed!

Referring to this, I added the following to emsdk.py and reran it.

import ssl
ssl._create_default_https_context = ssl._create_unverified_context

After running the commands below again, the installation was successful in my environment ✨

$ python3 ./emsdk.py install latest
$ python3 ./emsdk.py activate latest
$ source ./emsdk_env.sh

2. Compile raylib library

Next, we need to compile the raylib library for HTML5 and generate libraylib.a, so let's proceed with the compilation.
Clone the raylib repository and create libraylib.a by referring to this.

$ git clone git@github.com:raysan5/raylib.git
$ cd raylib/src
$ emcc -c rcore.c -Os -Wall -DPLATFORM_WEB -DGRAPHICS_API_OPENGL_ES2
$ emcc -c rshapes.c -Os -Wall -DPLATFORM_WEB -DGRAPHICS_API_OPENGL_ES2
$ emcc -c rtextures.c -Os -Wall -DPLATFORM_WEB -DGRAPHICS_API_OPENGL_ES2
$ emcc -c rtext.c -Os -Wall -DPLATFORM_WEB -DGRAPHICS_API_OPENGL_ES2
$ emcc -c rmodels.c -Os -Wall -DPLATFORM_WEB -DGRAPHICS_API_OPENGL_ES2
$ emcc -c utils.c -Os -Wall -DPLATFORM_WEB
$ emcc -c raudio.c -Os -Wall -DPLATFORM_WEB

$ emar rcs libraylib.a rcore.o rshapes.o rtextures.o rtext.o rmodels.o utils.o raudio.o

4. Compile raylib game for web

Set the EMSDK_PATH required when compiling raylib-game-template/src/Makefile as a web app.
Note: EMSDK is an environment variable set when running source ./emsdk_env.sh.

ifeq ($(PLATFORM),PLATFORM_WEB)
    # Emscripten required variables
    EMSDK_PATH         ?= $(EMSDK) # ⇐ Fix this!!
    EMSCRIPTEN_PATH    ?= $(EMSDK_PATH)/upstream/emscripten
    CLANG_PATH          = $(EMSDK_PATH)/upstream/bin
    PYTHON_PATH         = $(EMSDK_PATH)/python/3.9.2-1_64bit
    NODE_PATH           = $(EMSDK_PATH)/node/14.15.5_64bit/bin
    export PATH         = $(EMSDK_PATH);$(EMSCRIPTEN_PATH);$(CLANG_PATH);$(NODE_PATH);$(PYTHON_PATH):$$(PATH)
endif

Once ready, compile using make PLATFORM=PLATFORM_WEB -e. If the compilation is successful, it's all good if the following files are created.

.
├── raylib_game.data
├── raylib_game.html
├── raylib_game.js
├── raylib_game.wasm

5. Test raylib game on web

Now that we've come this far, let's start a local web server and check it in the browser.
Run the following command in raylib-game-template/src.

$ python3 -m http.server 8080

Access http://localhost:8080/raylib_game.html in your browser, and if it displays as follows, you're good to go ✨

Simplifying to a Minimal Configuration

Now that the sample is running, let's simplify the setup to a minimal configuration so we can experiment with various features.
Since we'll only be using raylib-game-template/src/raylib_game.c, modify PROJECT_SOURCE_FILES in the Makefile as follows:

PROJECT_SOURCE_FILES ?= \
    raylib_game.c

This removes other files (*.c) from the compilation target.
Next, modify raylib_game.c as follows:

#include "raylib.h"
#if defined(PLATFORM_WEB)
    #include <emscripten/emscripten.h>
#endif

void UpdateDrawFrame(void)
{
    BeginDrawing();
        ClearBackground(RAYWHITE);
        DrawText("Hello World!", 190, 200, 20, BLACK);
    EndDrawing();
}

int main(void)
{
    InitWindow(800, 450, "raylib");

#if defined(PLATFORM_WEB)
    emscripten_set_main_loop(UpdateDrawFrame, 60, 1);
#else
    SetTargetFPS(60);
    while (!WindowShouldClose())
    {
        UpdateDrawFrame();
    }
#endif

    CloseWindow();

    return 0;
}

Compiling and running the code above should display a screen like this:

# Compile for desktop
$ make -e
# Compile for web app
$ make PLATFORM=PLATFORM_WEB -e

Trying Out Various Shapes

I'll try displaying various shapes like rectangles, circles, lines, and triangles.
The relevant module for this is rshapes.

Drawing Rectangles

Use the DrawRectangle* functions. The definitions can be found here.

void DrawRectangles(void)
{
    DrawRectangle(100, 50, 120, 60, RED); // Display a filled rectangle
    DrawRectangleLines(100, 150, 120, 60, BLUE); // Display rectangle outlines
    DrawRectangleGradientV(100, 250, 120, 60, MAROON, ORANGE); // Vertical gradient
    Rectangle rec = { 100, 350, 120, 60 };
    DrawRectangleRounded(rec, 0.2f, 0, LIGHTGRAY); // Rounded rectangle
}

void UpdateDrawFrame(void)
{
    BeginDrawing();
        ClearBackground(RAYWHITE);
        DrawRectangles(); // Changed!
    EndDrawing();
}

Drawing Circles

Use the DrawCircle* functions. The definitions are here.

void DrawCircles(void)
{
    DrawCircle(100, 100, 20.0f, RED); // Display a filled circle
    Vector2 center = { 200, 100 };
    DrawCircleSector(center, 20.0f, 0.0f, 180.0f, 10, BLUE); // Display a sector of a circle
    DrawCircleGradient(300, 100, 20.0f, MAROON, ORANGE); // Gradient from the edge towards the center of the circle
    DrawCircleLines(400, 100, 20.0f, LIGHTGRAY); // Display circle outlines
}

void UpdateDrawFrame(void)
{
    BeginDrawing();
        ClearBackground(RAYWHITE);
        DrawCircles(); // Changed!
    EndDrawing();
}

Drawing Lines

Use the DrawLine* functions. The definitions are here.

void DrawLines(void)
{
    DrawLine(10, 10, 210, 10, RED); // Display a line
    {
        Vector2 startPos = { 10, 50 };
        Vector2 endPos = { 210, 50 };
        DrawLineEx(startPos, endPos, 20, BLUE); // Display a line with specified thickness
    }
    {
        Vector2 startPos = { 10, 100 };
        Vector2 endPos = { 210, 120 };
        DrawLineBezier(startPos, endPos, 10, MAROON); // Bezier curve with ease-in-out
    }
    {
        Vector2 vecs[] = {{ 10, 150 }, {50, 160}, {100, 145}, {210, 150}};
        DrawLineStrip(vecs, 4, ORANGE); // Specify multiple points
    }
}

void UpdateDrawFrame(void)
{
    BeginDrawing();
        ClearBackground(RAYWHITE);
        DrawLines(); // Changed!
    EndDrawing();
}

Drawing Triangles

Use the DrawTriangle* functions. The definitions are here.

void DrawTriangles(void)
{
    {
        Vector2 v1 = { 60, 10 };
        Vector2 v2 = { 10, 100 };
        Vector2 v3 = { 100, 100 };
        DrawTriangle(v1, v2, v3, RED); // Display a triangle by specifying 3 points
    }
    {
        Vector2 vecs[] = {{ 60, 110 }, { 10, 200 }, { 100, 200 }, { 120, 150 }};
        DrawTriangleFan(vecs, 4, BLUE); // Displays as a polygon if points outside the triangle lines are specified
    }
    {
        Vector2 vecs[] = {{ 60, 210 }, { 10, 300 }, { 100, 300 }, { 120, 250 }};
        DrawTriangleStrip(vecs, 4, ORANGE); // Ignored if points outside the triangle lines are specified
    }
}

void UpdateDrawFrame(void)
{
    BeginDrawing();
        ClearBackground(RAYWHITE);
        DrawTriangles(); // Changed!
    EndDrawing();
}

VSCode Setup (Bonus: If needed)

To make development smoother, you can install the following extensions:

Troubleshooting

The following error may occur while compiling a desktop app:

ld: warning: ignoring file ../../raylib/src/libraylib.a, building for macOS-x86_64
but attempting to link with file built for unknown-unsupported file format

This happens because it is referencing raylib/src/libraylib.a which was created for the web app. Commenting out the following item in the Makefile will allow compilation to proceed, although warnings will still appear.

# RAYLIB_PATH           ?= ../../raylib

Conclusion

My personal impression is that raylib seems suitable for small hobbies or education, much like Raspberry Pi ✨ There are also community ports for other languages, so you can try it out in your preferred language.

References

Discussion