hizli-baslangic

Türkçe | English version

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 painter.IsValid() 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