Skip to content

sync[bot]: from source of truth: GraphicalPlayground/gp-source-of-truth@main #146

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
graphical-playground wants to merge 1 commit into from
Closed

sync[bot]: from source of truth: GraphicalPlayground/gp-source-of-truth@main #146

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
214 changes: 2 additions & 212 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,219 +8,9 @@
# [@GraphicalPlayground](https://github.com/GraphicalPlayground)/gp-engine

🌎 Read this in: [English](README.md) | [Español](translations/es/README.md) | [Français](translations/fr/README.md) | [简体中文](translations/zh-cn/README.md)
<!-- gp-source-of-truth:custom:start -->
<!-- gp:protected:start -->

**Table of content**
[Overview](#overview)
┕ [Getting Started](#getting-started)
┕ [Prerequisites](#prerequisites)
┕ [Building the Engine](#building-the-engine)
┕ [Gallery](#gallery)
[Architecture](#architecture)
┕ [Core Systems](#core-systems)
┕ [Progressive Abstractions](#progressive-abstractions)
┕ [Rendering Pipelines (OpenGL / Vulkan / DirectX / ...)](#rendering-pipelines-opengl--vulkan--directx--)
[Usage & Experimentation](#usage--experimentation)
┕ [Sample Projects](#sample-projects)
┕ [Shader Programming](#shader-programming)
[Documentation](#documentation)
┕ [API Reference](#api-reference)
┕ [Learning Paths](#learning-paths)
[Contributing](#contributing)
┕ [Code of Conduct](#code-of-conduct)
┕ [Security](#security)
┕ [License](#license)
┕ [Donations](#donations)
[Contact](#contact)

## Overview

**gp-engine** is a C++ graphics engine specifically engineered for learning, experimentation, and
teaching modern rendering architectures.

Built around a **Deconstructionist Pedagogy**, the engine bridges the gap between high-level creative
tools and low-level hardware programming. Rather than hiding complexity behind a black-box system,
`gp-engine` provides progressive abstractions over modern rendering APIs (OpenGL and Vulkan). It
empowers users to tear down, study, modify, and cleanly reimplement core graphics concepts, from
foundational rendering algorithms to advanced GPU architectures, without needing to master millions
of lines of legacy code.

### Getting Started

Welcome to the Graphical Playground ecosystem. To start experimenting with `gp-engine`, you will need
to clone the repository and set up the build environment. The engine is built using a modern C++23
toolchain and relies on a modular, production-grade architecture.

First, clone the repository along with its submodules:

```bash
git clone --recursive https://github.com/GraphicalPlayground/gp-engine.git
cd gp-engine
```

### Prerequisites

Because `gp-engine` takes advantage of modern graphics APIs and the latest C++ features, ensure
your development environment meets the following requirements:

- **Compiler**: A C++23 compatible compiler (GCC 13+, Clang 16+, or MSVC 19.38+)
- **Build System**: CMake (Version 3.20 or higher)
- **Graphics Drivers**: Up-to-date GPU drivers with support for:
- Vulkan `tba`
- OpenGL `tba`
- DirectX `tba` (Windows only)
- Metal `tba` (macOS only)

### Building the Engine

The engine uses CMake Presets to simplify configuration and building across different platforms and
environments. We recommend performing an out-of-source build, which the presets handle automatically
to keep your project directory clean.

> **Important Prerequisites**: Our Linux presets specifically require the Clang compiler
(`clang` and `clang++`) as well as `ccache` (compiler cache) to be installed on your system prior to
building. For Windows, `clang-cl` is required, and for macOS, the default `clang` compiler is sufficient.

**1. List available presets:**

First, check the available configure presets for your specific platform (Linux, Windows, or macOS):

```bash
cmake --list-presets
```

_Example output:_

```text
Available configure presets:

"linux-release"
"linux-debug"
"linux-profile"
"linux-development"
```

> (Note: You will see `windows-...` or `macos-...` prefixes depending on your operating system).

For detailed information on what each configuration entails, please refer to the
[Build Type documentation](https://docs.graphical-playground.com/docs/gp-engine/Programming%20With%20C++/GP%20Build%20Tool/Build%20Type).

**2. Configure the project:**

Select the appropriate preset for your environment and generate the build files. For example, to
configure a release build on Linux:

```bash
cmake --preset linux-development
```

> Note: You can still append flags like `-DGP_USE_VULKAN=ON` or `-DGP_USE_OPENGL=ON` to your preset
command depending on the rendering backend you wish to target. Read the [documentation](#documentation)
for more details on configuring rendering backends.

**3. Compile the project:**

Build the engine using the corresponding build preset. You can also append the `-j` flag to utilize
multiple CPU cores and speed up the process:

```bash
cmake --build --preset linux-development -j$(nproc)
```

Once the build successfully completes, the compiled binaries and sample experimentation projects
will be located in the `binaries/bin/` directory. You can run one of the basic sample executables
to verify that the rendering pipeline and windowing context have initialized correctly.

### Gallery

_Screenshots and clips of `gp-engine` in action are coming soon. In the meantime, check the
[Learning Paths](https://graphical-playground.com/discover) for a preview of what you'll be building._

## Architecture

`gp-engine` is organized as a set of independent, composable systems rather than a single monolithic
runtime. Each system is designed to be studied and swapped out in isolation, in keeping with the
project's Deconstructionist Pedagogy. The engine targets Windows, Linux, macOS, iOS, Android, and
WASM, and is built under strict portability constraints: no RTTI, no exceptions, and correctness
across both endianness and architecture (x86_64 and ARM64).

### Core Systems

The engine's foundation is a collection of hand-built, dependency-light core systems:

- **Math Library**: A high-performance, SIMD-optimized math library for vectors, matrices, and
quaternions.
- **Memory Management**: A custom memory allocator and pool system designed for low-latency
graphics workloads.
- **Foundational Containers**: Lightweight, cache-friendly data structures for graphics programming.
- **Cryptography & Hashing**: A set of cryptographic primitives and hashing functions for secure
resource management.
- **Error & Diagnostics**: A robust error handling and logging system for debugging and profiling.
- **Concepts & Type Traits**: A collection of C++ concepts and type traits to enforce compile-time
correctness and improve code clarity.

### Progressive Abstractions

Rather than exposing a single fixed API, `gp-engine` layers its abstractions so learners can enter at
the level that matches their experience and descend further as they're ready:

1. **Foundations**: core algorithms and data structures with no rendering API in sight.
2. **Abstracted Rendering**: a simplified, engine-level API for getting pixels on screen quickly.
3. **Native APIs**: direct access to OpenGL and Vulkan calls for learners who want to work as close
to the hardware as possible.

Each layer is documented so you can trace exactly how a call at the top eventually reaches the GPU.

### Rendering Pipelines (OpenGL / Vulkan / DirectX / ...)

`gp-engine` currently ships with DirectX and Vulkan rendering backends, selectable at configure time
via CMake flags (see [Building the Engine](#building-the-engine)). OpenGL (Linux/macOS) and Metal
(macOS) backends are planned to round out native support on every target platform. Each backend
implements the same engine-facing abstraction, so sample projects and learning material remain
portable across APIs.

## Usage & Experimentation

Once built, `gp-engine` is meant to be explored hands-on: run the sample projects, read through the
corresponding source, then modify or reimplement pieces yourself.

### Sample Projects

The `samples/` directory is organized to mirror the Learning Paths, starting with minimal
"hello triangle"-style projects and building up toward full rendering pipelines. Check the directory
itself for the current list of runnable samples, and see the
[Learning Paths](https://graphical-playground.com/discover) for the recommended order to work
through them.

## Documentation

Comprehensive documentation for `gp-engine` is hosted on our main documentation portal. Whether you
are building your first triangle or writing a custom Vulkan rendering pass, our guides are designed
to support your experimentation.

- [**Main Documentation Portal**](https://docs.graphical-playground.com)
- [**Engine Introduction**](https://docs.graphical-playground.com/docs/engine/intro)

### API Reference

Our detailed C++ API documentation outlines the core classes, rendering pipelines, and math
libraries that make up `gp-engine`. If you are extending the engine or modifying its core
components, please review our C++ guides and formatting rules to ensure your code aligns
with the project's architecture.

- [**C++ API Reference**](https://docs.graphical-playground.com/docs/engine/cpp-api-reference)
- [**C++ Programming Guide**](https://docs.graphical-playground.com/docs/engine/programming-with-cpp)
- [**C++ Coding Standard**](https://docs.graphical-playground.com/docs/engine/programming-with-cpp/coding-standard)

### Learning Paths

Graphical Playground is built around a Deconstructionist Pedagogy, we want you to tear the engine
apart and learn how it works. To help guide your studies, we have curated structured learning
paths that take you from foundational graphics programming concepts to advanced engine architecture.

- [**Explore the Learning Paths**](https://graphical-playground.com/discover)

<!-- gp-source-of-truth:custom:end -->
<!-- gp:protected:end -->
## Contributing

We welcome contributions from everybody! Whether you are fixing a bug, implementing a new features,
Expand Down
159 changes: 2 additions & 157 deletions translations/es/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,164 +8,9 @@
# [@GraphicalPlayground](https://github.com/GraphicalPlayground)/gp-engine

🌎 Leer en: [English](../../README.md) | [Español](../es/README.md) | [Français](../fr/README.md) | [简体中文](../zh-cn/README.md)
<!-- gp-source-of-truth:custom:start -->
<!-- gp:protected:start -->

**Tabla de contenido**
[Descripción](#descripción)
┕ [Primeros Pasos](#primeros-pasos)
┕ [Prerrequisitos](#prerrequisitos)
┕ [Compilar el Motor](#compilar-el-motor)
┕ [Galería](#galería)
[Arquitectura](#arquitectura)
┕ [Sistemas Principales](#sistemas-principales)
┕ [Abstracciones Progresivas](#abstracciones-progresivas)
┕ [Pipelines de Renderizado (OpenGL / Vulkan / DirectX / ...)](#pipelines-de-renderizado-opengl--vulkan--directx--)
[Uso y Experimentación](#uso-y-experimentación)
┕ [Proyectos de Ejemplo](#proyectos-de-ejemplo)
┕ [Programación de Shaders](#programación-de-shaders)
[Documentación](#documentación)
┕ [Referencia de API](#referencia-de-api)
┕ [Rutas de Aprendizaje](#rutas-de-aprendizaje)
[Contribuir](#contribuir)
┕ [Código de Conducta](#código-de-conducta)
┕ [Seguridad](#seguridad)
┕ [Licencia](#licencia)
┕ [Donaciones](#donaciones)
[Contacto](#contacto)

## Descripción

**gp-engine** es un motor de gráficos en C++ específicamente diseñado para el aprendizaje, la experimentación y la enseñanza de arquitecturas de renderizado modernas.

Construido alrededor de una **Pedagogía Deconstructivista**, el motor tiende un puente entre las herramientas creativas de alto nivel y la programación de hardware de bajo nivel. En lugar de ocultar la complejidad detrás de un sistema de caja negra, `gp-engine` proporciona abstracciones progresivas sobre las APIs de renderizado modernas (OpenGL y Vulkan). Permite a los usuarios desmontar, estudiar, modificar y reimplementar limpiamente los conceptos gráficos fundamentales, desde algoritmos de renderizado básicos hasta arquitecturas avanzadas de GPU, sin necesidad de dominar millones de líneas de código heredado.

### Primeros Pasos

Bienvenido al ecosistema Graphical Playground. Para comenzar a experimentar con `gp-engine`, necesitarás clonar el repositorio y configurar el entorno de compilación. El motor está construido con una cadena de herramientas moderna C++23 y se basa en una arquitectura modular de grado de producción.

Primero, clona el repositorio junto con sus submódulos:

```bash
git clone --recursive https://github.com/GraphicalPlayground/gp-engine.git
cd gp-engine
```

### Prerrequisitos

Dado que `gp-engine` aprovecha las APIs gráficas modernas y las últimas características de C++, asegúrate de que tu entorno de desarrollo cumpla con los siguientes requisitos:

- **Compilador**: Un compilador compatible con C++23 (GCC 13+, Clang 16+, o MSVC 19.38+)
- **Sistema de Compilación**: CMake (Versión 3.20 o superior)
- **Controladores Gráficos**: Controladores GPU actualizados con soporte para:
- Vulkan `tba`
- OpenGL `tba`
- DirectX `tba` (solo Windows)
- Metal `tba` (solo macOS)

### Compilar el Motor

El motor utiliza CMake Presets para simplificar la configuración y compilación en diferentes plataformas y entornos. Recomendamos realizar una compilación fuera del árbol de fuentes, que los presets manejan automáticamente para mantener limpio el directorio de tu proyecto.

**Prerrequisitos importantes para Linux**: Nuestros presets de Linux requieren específicamente el compilador Clang (`clang` y `clang++`) así como `ccache` (caché del compilador) instalados en tu sistema antes de compilar.

**1. Listar los presets disponibles:**

Primero, comprueba los presets de configuración disponibles para tu plataforma específica (Linux, Windows o macOS):

```bash
cmake --list-presets
```

_Ejemplo de salida:_

```text
Available configure presets:

"linux-release"
"linux-debug"
"linux-profile"
"linux-development"
```

> (Nota: Verás prefijos `windows-...` o `macos-...` según tu sistema operativo).

Para información detallada sobre lo que implica cada configuración, consulta la
[documentación sobre Tipos de Compilación](https://docs.graphical-playground.com/docs/gp-engine/Programming%20With%20C++/GP%20Build%20Tool/Build%20Type).

**2. Configurar el proyecto:**

Selecciona el preset adecuado para tu entorno y genera los archivos de compilación. Por ejemplo, para configurar una compilación de desarrollo en Linux:

```bash
cmake --preset linux-development
```

> Nota: Puedes añadir flags como `-DGP_USE_VULKAN=ON` o `-DGP_USE_OPENGL=ON` a tu comando de preset según el backend de renderizado que desees usar. Lee la [documentación](#documentación) para más detalles sobre la configuración de backends de renderizado.

**3. Compilar el proyecto:**

Compila el motor usando el preset de compilación correspondiente. También puedes añadir el flag `-j` para utilizar múltiples núcleos de CPU y acelerar el proceso:

```bash
cmake --build --preset linux-development -j$(nproc)
```

Una vez que la compilación se complete con éxito, los binarios compilados y los proyectos de ejemplo estarán ubicados en el directorio `binaries/bin/`. Puedes ejecutar uno de los ejecutables de ejemplo básicos para verificar que el pipeline de renderizado y el contexto de ventana se hayan inicializado correctamente.

### Galería

_en progreso..._

## Arquitectura

_en progreso..._

### Sistemas Principales

_en progreso..._

### Abstracciones Progresivas

_en progreso..._

### Pipelines de Renderizado (OpenGL / Vulkan / DirectX / ...)

_en progreso..._

## Uso y Experimentación

_en progreso..._

### Proyectos de Ejemplo

_en progreso..._

### Programación de Shaders

_en progreso..._

## Documentación

La documentación completa de `gp-engine` está alojada en nuestro portal de documentación principal. Ya sea que estés dibujando tu primer triángulo o escribiendo un renderizado Vulkan personalizado, nuestras guías están diseñadas para apoyar tu experimentación.

- [**Portal de Documentación Principal**](https://docs.graphical-playground.com)
- [**Introducción al Motor**](https://docs.graphical-playground.com/docs/engine/intro)

### Referencia de API

Nuestra detallada documentación de la API de C++ describe las clases principales, los pipelines de renderizado y las bibliotecas matemáticas que componen `gp-engine`. Si estás extendiendo el motor o modificando sus componentes principales, revisa nuestras guías de C++ y las normas de formato para garantizar que tu código se alinee con la arquitectura del proyecto.

- [**Referencia de la API de C++**](https://docs.graphical-playground.com/docs/engine/cpp-api-reference)
- [**Guía de Programación en C++**](https://docs.graphical-playground.com/docs/engine/programming-with-cpp)
- [**Estándar de Código C++**](https://docs.graphical-playground.com/docs/engine/programming-with-cpp/coding-standard)

### Rutas de Aprendizaje

Graphical Playground está construido alrededor de una Pedagogía Deconstructivista: queremos que desmontes el motor y aprendas cómo funciona. Para orientar tus estudios, hemos elaborado rutas de aprendizaje estructuradas que te llevan desde los conceptos fundamentales de la programación gráfica hasta la arquitectura avanzada de motores.

- [**Explorar las Rutas de Aprendizaje**](https://graphical-playground.com/discover)

<!-- gp-source-of-truth:custom:end -->
<!-- gp:protected:end -->
## Contribuir

¡Damos la bienvenida a las contribuciones de todos! Ya sea que estés corrigiendo un error, implementando nuevas funcionalidades o mejorando nuestra documentación, tu ayuda es apreciada. Consulta nuestra guía completa [CONTRIBUTING.md](./CONTRIBUTING.md) para información detallada sobre nuestros estándares y el proceso de revisión de pull requests.
Expand Down
Loading