SDLPainter — Hızlı Başlangıç

Bu rehber SDLPainter'ı ilk defa kullananlar içindir.

Beş dakikada çalışan bir pencere ve birkaç şekil çizdirmek için doğru yerdesiniz. Kütüphanenin mimarisi ve diğer üst seviye hususlar için Mimari Genel Bakış sayfasına göz atabilirsiniz.

1. Önkoşullar

Araç	Minimum Sürüm	Notlar
C++ derleyicisi	C++17 destekleyen GCC 11+, Clang 14+, MSVC 2022
CMake	3.21	`PROJECT_IS_TOP_LEVEL`, `$<TARGET_RUNTIME_DLLS>`, presets v3 için
Conan	2.x	`pip install conan`
Git	—	repoyu klonlamak için
OpenGL sürücüsü	3.3 Core	Çoğu sistemde mevcut
Vulkan loader	1.1+ runtime (opsiyonel)	Hedef API 1.1; Conan paketi `vulkan-loader/1.3.290` (geri uyumlu)

2. Kurulum

# 1) Klonla
git clone https://github.com/yazilimperver/sdl-painter.git
cd sdl-painter
 
# 2) Bağımlılıkları yükle (debug build için)
conan install . --output-folder=build/linux-debug/generators \
    --build=missing -s build_type=Debug
 
# 3) Configure + build
cmake --preset linux-debug
cmake --build --preset linux-debug
 
# 4) Demo'yu çalıştır
./build/linux-debug/examples/primitives

‍Preset adı --output-folder ile eşleşmek zorunda: projenin CMakePresets.json dosyası her preset için toolchain yolunu build/<preset>/generators/... altında arıyor.

Windows / MSVC için preset adları windows-debug ve windows-release şeklindedir (--output-folder=build/windows-debug/generators). Cross-compile için Dockerfile içindeki windows-cross stage'i ve windows-mingw-debug / windows-mingw-release presetleri kullanılır.

NOT: Conan install ve benzeri çağrıları, CMake presetleri içerisine de alacak bir takım çözümler mevcut, bununla birlikte şu an için bu şekilde durmasının daha iyi olduğunu düşünüyorum ileride belki bu opsiyonu da değerlendirebiliriz.

2.1 Windows (Visual Studio 2022) — Manuel

# 0. VS 2022 ortam değişkenlerini yüklüyoruz
$vsInstallPath = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -latest -property installationPath
Import-Module "$vsInstallPath\Common7\Tools\Microsoft.VisualStudio.DevShell.dll"
Enter-VsDevShell -VsInstallPath $vsInstallPath -DevCmdArguments "-arch=x64"
 
# 1. Conan profili oluşturuyoruz (ilk seferde). Ileride bunlari da sağlıyor olacağım
conan profile detect
 
# 2. Bağımlılıkları yüklüyoruz
conan install . --output-folder=build/windows-debug/generators --build=missing -s build_type=Debug
 
# 3. Derle
cmake --preset windows-debug
cmake --build --preset windows-debug

2.2 Script ile Derleme

Tüm scriptler projenin root dizininden çalıştırılmalıdır. Argümanların tam listesi için Script Referansı *(İngilizce)*.

chmod +x scripts/*.sh
 
./scripts/build.sh              # Derle (Debug, varsayılan)
./scripts/build.sh Release      # Release derle
./scripts/build.sh --docs       # Build + API dokümantasyonu
./scripts/run-tests.sh          # Testleri çalıştır
./scripts/format-check.sh       # Format kontrolü

.\scripts\Build.ps1             # Derle (Debug, varsayılan)
.\scripts\Build.ps1 Release     # Release derle
.\scripts\Build.ps1 -Docs       # Build + API dokümantasyonu
.\scripts\Run-Tests.ps1         # Testleri çalıştır
.\scripts\Format-Check.ps1      # Format kontrolü

2.3 CMake Preset Referansı

Preset	Platform	Build Type	Notlar
`linux-debug`	Linux	Debug	CI'da da kullanılır
`linux-release`	Linux	Release	CI'da da kullanılır
`linux-debug-asan`	Linux	Debug	ASan + UBSan aktif
`windows-debug`	Windows	Debug	MSVC, Visual Studio 17 2022
`windows-release`	Windows	Release	MSVC, Visual Studio 17 2022
`windows-mingw-debug`	Windows (cross)	Debug	Linux host'ta MinGW-w64 cross-compile, Vulkan'sız
`windows-mingw-release`	Windows (cross)	Release	Linux host'ta MinGW-w64 cross-compile, Vulkan'sız

2.4 CMake Seçenekleri

Seçenek	Varsayılan	Açıklama
`SDLPAINTER_WITH_VULKAN`	`OFF`	Vulkan backend
`SDLPAINTER_BUILD_EXAMPLES`	`ON`	Örnek uygulamalar
`SDLPAINTER_BUILD_TESTS`	`ON`	GTest birim testleri
`ENABLE_SANITIZERS`	`OFF`	ASan + UBSan (GCC/Clang)

Vulkan dahil tüm özelliklerle derleme:

conan install . --output-folder=build/linux-debug/generators --build=missing \
    -s build_type=Debug -o "&:with_vulkan=True"
cmake --preset linux-debug
cmake --build --preset linux-debug

3. İlk Uygulama — "Hello, Rectangle"

Basit bir uygulama oluşturmak için, aşağıdaki dosyayı main.cpp olarak kaydedin:

#include <SDL3/SDL.h>
#include "sdl_painter/painter.h"
#include "sdl_painter/pen.h"
#include "sdl_painter/brush.h"
 
int main() {
  SDL_Init(SDL_INIT_VIDEO);
 
  // OpenGL 3.3 Core context için ipuçları
  SDL_GL_SetAttribute(SDL_GL_CONTEXT_MAJOR_VERSION, 3);
  SDL_GL_SetAttribute(SDL_GL_CONTEXT_MINOR_VERSION, 3);
  SDL_GL_SetAttribute(SDL_GL_CONTEXT_PROFILE_MASK,
                      SDL_GL_CONTEXT_PROFILE_CORE);
 
  SDL_Window* window = SDL_CreateWindow(
      "SDLPainter Hello", 800, 600,
      SDL_WINDOW_OPENGL | SDL_WINDOW_RESIZABLE);
 
  // Painter'ı bir scope'a al → window'dan ÖNCE yıkılsın
  {
    sdl_painter::Painter painter(window,
                                  sdl_painter::RendererBackend::kOpenGL);
    if (!painter.IsValid()) {
      SDL_DestroyWindow(window);
      SDL_Quit();
      return 1;
    }
 
    bool running = true;
    while (running) {
      SDL_Event event;
      while (SDL_PollEvent(&event)) {
        if (event.type == SDL_EVENT_QUIT) running = false;
      }
 
      painter.Begin();
      painter.Clear({30, 30, 40, 255});
 
      painter.SetBrush(sdl_painter::Brush({80, 160, 220, 255}));
      painter.FillRect(100.0f, 100.0f, 200.0f, 150.0f);
 
      painter.SetPen(sdl_painter::Pen({255, 200, 50, 255}, 3.0f));
      painter.DrawCircle(500.0f, 300.0f, 80.0f);
 
      painter.End();
    }
  }
 
  SDL_DestroyWindow(window);
  SDL_Quit();
  return 0;
}

Önemli Detaylar

Satır	Neden	Atlanırsa
`SDL_GL_SetAttribute(...CORE)`	OpenGL 3.3 Core profile şart	Compatibility profile'da çalışabilir ama undefined
`Painter` scope içinde	GL context window'a bağlı	`glDelete*` çağrısı 1282 hatası verir
`painter.IsValid()`	Constructor sessizce başarısız olabilir	Sonraki çağrılarda crash
`painter.Begin()` / `painter.End()`	Frame sınırı	Çizimler ekrana yansımaz

4. Temel API Özeti

4.1 Stil Ayarları

painter.SetPen(sdl_painter::Pen(color, width));   // çerçeve / çizgi
painter.SetBrush(sdl_painter::Brush(color));      // dolgu
painter.SetOpacity(0.5f);                         // global alpha [0,1]

Pen::NoPen() ve Brush::NoBrush() görünmez varyantlardır; o anki çizimler atlanır (GPU yüküne girmez).

4.2 Çizim Primitifleri

Stroke (çerçeve)	Fill (dolgu)
`DrawLine(x1, y1, x2, y2)`	—
`DrawRect(x, y, w, h)`	`FillRect(x, y, w, h)`
`DrawCircle(cx, cy, r)`	`FillCircle(cx, cy, r)`
`DrawEllipse(cx, cy, rx, ry)`	`FillEllipse(cx, cy, rx, ry)`
`DrawPolygon(points)`	`FillPolygon(points)`
`DrawPolyline(points)`	—

4.3 Transform Stack

painter.Save();
painter.Translate(400.0f, 300.0f);
painter.Rotate(45.0f);                   // derece
painter.Scale(1.5f, 1.5f);
painter.FillRect(-50.0f, -50.0f, 100.0f, 100.0f);
painter.Restore();                       // önceki state geri yüklenir

Save/Restore sayısı dengeli olmalı.

4.4 Image (Phase 3)

sdl_painter::Image img("assets/sprite.png");
if (img.IsValid()) {
  painter.DrawImage(img, 100.0f, 50.0f);            // orijinal boyut
  painter.DrawImage(img, sdl_painter::Rect{200, 50, 64, 64});  // ölçekli
}

İlk çizimde GPU'ya yüklenir, sonraki çizimlerde cache kullanılır.

4.5 Metin (Phase 4)

auto font = std::make_shared<sdl_painter::Font>("assets/font.ttf", 24);
painter.SetFont(font);
painter.SetPen(sdl_painter::Pen({255, 255, 255, 255}));  // pen rengi tint
painter.DrawText(50.0f, 100.0f, "Merhaba Dünya!");
 
painter.DrawText(sdl_painter::Rect{0, 200, 800, 50},
                 "Ortalı metin",
                 sdl_painter::Alignment::kCenter);

4.6 Clipping

painter.SetClipRect({100, 100, 400, 300});
// Sadece bu dikdörtgen içine çizim görünür
painter.FillCircle(500, 250, 200);  // bir kısmı kırpılır
painter.ClearClip();

Scissor tabanlı, eksen-hizalı dikdörtgen.

5. Vulkan Backend'e Geçiş

// OpenGL window flag'i yerine Vulkan flag'i:
SDL_Window* window = SDL_CreateWindow(
    "Vulkan Demo", 800, 600,
    SDL_WINDOW_VULKAN | SDL_WINDOW_RESIZABLE);
 
sdl_painter::Painter painter(window,
                              sdl_painter::RendererBackend::kVulkan);

‍Vulkan backend için kütüphane with_vulkan=True ile build edilmiş olmalı: conan install . -o "&:with_vulkan=True".

Diğer hiçbir kullanıcı kodu değişmez. Aynı painter.FillRect, painter.DrawText, painter.Save çağrıları çalışır. Bu IRenderer soyutlamasının somut karşılığıdır.

6. Faz Bazlı Demo Uygulamaları

examples/ dizini her özellik için bağımsız bir demo içerir. Yeni başlayanlar için önerilen okuma sırası:

Demo	Konu	İlgili API
`primitives.cpp`	Tüm temel primitifler	`DrawRect`, `FillCircle`, `DrawPolyline`
`transforms.cpp`	Transform stack	`Save`/`Restore`, `Translate`/`Rotate`/`Scale`
`clipping.cpp`	Clipping	`SetClipRect` / `ClearClip`
`images.cpp`	Image / texture	`Image`, `DrawImage`
`text.cpp`	Metin	`Font`, `DrawText`, `Alignment`
`vulkan_clear.cpp`	Vulkan: pencereyi temizle	`RendererBackend::kVulkan`
`vulkan_triangles.cpp`	Vulkan: ilk üçgenler	—
`vulkan_textured.cpp`	Vulkan: image	—
`vulkan_demo.cpp`	Vulkan: tüm primitifler	—
`vulkan_text.cpp`	Vulkan: metin	—

7. Sık Karşılaşılan Sorunlar

7.1 <tt>painter.IsValid()</tt> false dönüyor

OpenGL: window flag'inde SDL_WINDOW_OPENGL var mı?
OpenGL: 3.3 Core context attribute'leri set edildi mi?
Vulkan: window flag'inde SDL_WINDOW_VULKAN var mı? Kütüphane with_vulkan=True ile build edildi mi?

7.2 Çizimler ekranda görünmüyor

painter.Begin() ve painter.End() arasında mı?
Pen veya Brush Transparent mi (alpha=0)?
Y koordinatı ekran dışında mı? (Y=0 üstte, aşağı pozitif)
Transform içinde miyiz? Save/Restore dengesi bozulmuş olabilir.

7.3 OpenGL 1282 hatası uygulama kapanırken

Painter instance, SDL_DestroyWindow'dan önce yok edilmeli. En basit yöntem: Painter'ı bir scope (kıvrımlı blok) içine alın.

7.4 Performans düşük

Her draw call'dan önce SetPen/SetBrush değiştirmeyin (renk değişimi flush tetiklemez ama opacity değişimi tetikler).
Metin için Font::GetGlyph ilk çağrıda maliyetlidir; sonra cache parasız.
Aynı texture'lı sprite'ları arka arkaya çizmek tek draw call'da çıkar.

8. Sonraki Adımlar

📐 Sınıf Diyagramı — API'nin tam yapısı
🔄 Akış Diyagramları — Frame yaşam döngüsü, batch flush, transform stack
📜 Özellik Listesi — Desteklenen tüm primitifler
💡 Örnekler — Daha fazla kullanım örneği
🏗️ Yazılım Mühendisliği Perspektifi — Tasarım kararlarının gerekçeleri