BasicC/BasicSDL

SDL jest wieloplatformową biblioteką C/C++ ułatwiającą m. in. korzystanie z grafiki, dźwięku, urządzeń, plików. Dzięki BasicC korzystanie z SDL jest jeszcze prostsze i wygodniejsze, daje też dodatkowe funkcje.
Dostępna jest dokumentacja i kurs SDL w języku polskim: https://eduinf.waw.pl/inf/prg/011_sdl2/index.php

Instalacja SDL

Uwaga: jeśli chcemy, by programy działały również w starszych wersjach systemu Android raczej powinniśmy zainstalować starszą wersję SDL, np. 2.08.

Linux

Najprościej skorzystać z instalatora pakietów, np. Synaptic. Wiele dystrybucji ma już zainstalowana bibliotekę SDL, należy jednak pamiętać by była też zainstalowana wersja deweloperska (dev). Analogicznie instalujemy dodatki takie jak SDL_mixer.

Windows

Poprostu pobieramy wersję deweloperską (dev) i rozpakowujemy w wybranym katalogu. Podobnie postępujemy z dodatkowymi bibliotekami. Pliki dodatków można skopiować do naszego katalogu SDL, w przeciwnym razie konieczne będzie podawanie kompilatorowi dodatkowej ścieżki do tych plików.

Kompilacja z SDL

Windows

Zalecane jest używanie podstawowej wersji kompilatora mingw. Można też zainstalować pakiet z interfejsem graficznym IDE np. DEV C++ lub Code::Blocks, w takim przypadku wskazane jest podanie w opcjach kompilatora odpowiednich ścieżek do katalogów bin, lib i include bibliotek SDL i ew. dodatków.

Opcje kompilacji z wiersza poleceń powinny wyglądać np. tak:
mojprogram.c -I Ścieżka_do_SDL2\include -L Ścieżka_do_SDL2\lib -lSDL2main -lSDL2 -o mojprogram

Jeśli używamy dodatkowych bibliotek też musimy poinformować o tym kompilator (właściwie linker), np. dla SDL_mixer dodajemy -lSDL2_mixer

Dokładniejszy opis instalacji i kompilacji jest np. tutaj:
https://www.matsson.com/prog/sdl2-mingw-w64-tutorial.php

Jeśli używamy interfejsu IDE w opcjach kompilatora podajemy następujące komendy dla linkera:
-lSDL2main -lSDL2
Jeśli używamy też np. miksera, dodajemy:
-lSDL2_mixer

Przykładowa konfiguracja edytora Geany z mingw i biblioteką SDL2_mixer:
W zaawansowanych właściwościach systemu do zmiennej środowiskowej Path dodajemy ścieżkę do kompilatora gcc, np. F:\mingw\bin (może być konieczne zrestartowanie systemu), ew. wpisujemy ją dalej w polu Polecenie przed gcc. W Geany otwieramy plik .c, wybieramy opcje Zbuduj->Zdefiniuj polecenia budowania, w polu Polecenie, dla etykiety Compile lub Build, wpisujemy: gcc -Wall "%f" -I F:\SDL2-2.0.20\i686-w64-mingw32\include\SDL2 -L F:\SDL2-2.0.20\i686-w64-mingw32\lib -lSDL2main -lSDL2 -I F:\SDL2_mixer-2.0.4\i686-w64-mingw32\include\SDL2 -L F:\SDL2_mixer-2.0.4\i686-w64-mingw32\lib -lSDL2_mixer -o "%e", gdzie odpowiednio podajemy ścieżki do katalogów include i lib SDL2 i SDL2_mixer, klikamy OK. Kompilację wykonujemy wciskając odpowiednio Skompiluj lub Buduj.
Jeśli używamy BasicSND i chcemy korzystać z MIDI MCI należy jeszcze dopisać -lwinmm

Linux

Przykładowy zestaw opcji kompilatora i linkera:
-Wall -o "%e" "%f" $(pkg-config --libs SDL2_image SDL2_ttf SDL2_mixer) $(sdl2-config --cflags) -lm
gdzie "%e" to nazwa pliku wykonywalnego, "%f" to nazwa pliku żródłowego

Android

Opis dotyczy kompilacji pod Linuksem.
Pobieramy wersję źródłową SDL. Instrukcja kompilacji znajduje się w pliku docs/README-android.md. Jeśli program ma poprawnie działać w starszych wersjach Androida zaleca się używanie SDL w wersji do 2.0.8 oraz NDK do r16b. Po stworzeniu projektu komendą ./androidbuild.sh w katalogu app/jni/src zamieszczamy pliki nagłówkowe i źródłowe programu (w tym Basic.h i BasicSDL.h), w app/src/main/assets/ inne pliki (w tym BASFont.bmp), biblioteki (kod źródłowy, np. katalog SDL2_mixer) najlepiej w app/jni.
Modyfikujemy plik app/jni/src/Android.mk:

w linii LOCAL_C_INCLUDES po spacji dopisujemy katalogi nagłówków bibliotek, np: $(LOCAL_PATH)/../SDL2_mixer
w LOCAL_SRC_FILES podajemy pliki .c do skompilowania
w LOCAL_SHARED_LIBRARIES dodajemy nazwy bibliotek, np: SDL2_mixer

Uwaga! Komenda androidbuild.sh usuwa zawartość katalogu projektu i tworzy nowy.

Po tych czynnościach można stworzyć .apk komendą ./gradlew installDebug Plik .apk powinien pojawić się w katalogu app/build/outputs/apk/. Aby program został automatycznie zainstalowany na urządzeniu z Androidem podłączonym przez USB należy włączyć w nim tryb programisty i opcję debugowania przez USB.

Niezalecane jest definiowanie stałej SDL_MAIN_HANDLED, jest to wymagane tylko pod Windowsem.
Zaleca się ustawianie tzw. colorkey dla każdego obrazka, nawet jeśli nie potrzebujemy przeźroczystości, w przeciwnym razie obrazek może nie być widoczny.

Konfiguracja BasicC dla SDL

Najprościej dodać pliki Basic.h, BasicSDL.h i BASFont.bmp do katalogu z naszym programem. Aby używać BasicC z SDL wystarczy na początku programu załączyć bibliotekę BasicSDL.h np. komendą:

#include "BasicSDL.h"

Jeśli chcemy zmienić domyślne opcję BasicSDL przed tą komendą należy wpisać dodatkowe dyrektywy preprocesora:

#define VSYNC "0"

Jeśli chcemy wyłączyć synchronizację programu z odświeżaniem monitora. Domyślnie opcja ta jest włączona, co oznacza, że po wywołaniu komendy ShowPage program jest wstrzymywany do momentu odświeżenia ekranu. Częstotliwość odświeżania jest zależna od ustawień monitora, zwykle wynosi ok 60 Hz.

#define WINDOWW szerokość_okna

#define WINDOWH wysokość_okna

Jeśli chcemy zmienić rozmiary okna w pikselach. Domyślny rozmiar wynosi 640x400, są to proporcje pośrednie między obrazem panoramicznym a tradycyjnym.

Innych zmian można dokonać modyfikując plik BasicSDL.h, np. zmienić ilość obsługiwanych joysticków, która domyślnie ustawiona jest na 4 komendą: #define MAXJOYS 4

#define FONTCOLORKEY K

Gdzie K to nr koloru przeźroczystego czcionki GPrint. 0 - tło przeźroczyste, 1 - czcionka przeźroczysta, -1 - brak przeźroczystości (napisy na czarnym tle). W niektórych systemach, np. Android, wartości te mogą być inne, a -1 może powodować niewyświetlanie tekstu.

#define SOUNDFREQUENCY F

F - częstotliwość do jakiej będą konwertowane i odtwarzane dźwięki, domyślnie 22050.

#define MAXJOYS J

J - maksymalna ilość kontrolerów gier, domyślnie 4.

#include "BasicSND.h"

Załącza bibliotekę obsługi dźwięku.

MIDI MCI

Jesli chcemy odtwarzać pliki MIDI korzystając z interfejsu MCI w Windows - BasicSDL.h powinien zawierać wpisy:

#define WIN32_LEAN_AND_MEAN
#include <windows.h>
#include <mmsystem.h>

#include "BasicGEM.h"

Wpisujemy w programie zamiast include "BasicSDL.h" jeśli chcemy korzystać z interfejsu graficznego GEM.

Dodatkowe biblioteki SDL

SDL_image.h - używane do ładowania obrazków w formacie innym niż BMP
SDL_ttf.h - obsługa czcionek TTF
SDL_mixer.h - odtwarzanie dźwięków

Jeśli nie używamy dodatkowych bibliotek można usunąć lub skomentować odpowiednie linie z #include

Zadeklarowane zmienne, stałe i funkcje

W BasicSDL.h zadeklarowanych jest szereg stałych, zmiennych i funkcji pomocniczych. Warto przejrzeć ten plik, by nie powielać wykorzystanych nazw w swoich programach.

Główna pętla programu

Używanie tej pętli jest w zasadzie wymagane do prawidłowego działania programów zawierających animacje, takich jak gry, jeśli mają działać prawidłowo w przeglądarce WWW. Powinien się w niej zawierać prawie cały program, poza komendami ładującymi, inicjującymi. Więcej informacji w rozdziale dotyczącym wersji WWW.

LOOP

Oznacza początek pętli. Powoduje dodatkowo detekcję zdarzeń systemowych, czyli wykonuje GetEvents.

ENDLOOP(W)

Koniec pętli głównej. Wyjście z pętli następuje gdy spełniony jest warunek W. Dodatkowo w zmiennej LOOPTIME zapisywany jest czas SDLTime, następnie wywoływane ShowPage.