Unnamed repository; edit this file 'description' to name the repository. (original) (raw)

Contents⊕

• Gamp: Graphics, Audio, Multimedia and Processing Framework
  • Git Repository
  • Goals
    * Coverage
  • Online WebAssembly Examples
  • Earlier Work
  • Status
    * TODO List
  • API Documentation
  • Supported Platforms
    * Build Dependencies
    * Build Procedure
    * Unit Testing
  • Build Status
  • IDE Integration
    * Eclipse
    * VSCodium or VS Code
  • Support & Sponsorship
  • Common issues
  • Changes

Original document location.

gamp /gămp/ noun

• A large baggy umbrella. > said to allude to Mrs. Gamp’s umbrella, in Dickens’s Martin Chuzzlewit.
• often: one that is untidily or loosely tied up > if you carry an umbrella use it tightly rolled and never as a gamp > — S. D. Barney

… further Gamp stands for Graphics, Audio, Multimedia and Processing, the same way as JogAmp, but natively plus using WebAssembly.

This project’s canonical repositories is hosted on Gothel Software.

Goals

Gamp addresses hardware accelerated graphics, audio, multimedia and processing. It is implemented in C++, supports WebAssembly and perhaps interfacing w/ other languages/systems.

Gamp replicates JogAmp’s experience natively via C++ in a condensed form, allowing a similar workflow on native targets and within the browser via WebAssembly.

Ironically this will bring back runs everywhere including_the web_.

Initial goal is to reimplement Graph/GraphUIutilizing Rami Santina’s Resolution independent NURBS curves rendering using programmable graphics pipeline 2011 (paper,slides).

Gamp uses jaulib for general purpose functionality including linear algebra and geometry.

Coverage

Video Clips

Online WebAssembly Examples

• Graph Rendering
  • GraphShapes01(source)
    * This is the first C++ example demonstrating Graph resolution independent GPU curve rendering. Multiple complex shapes are rotated with front- and back-face using per-pixel-lighting.
• Primitive Tesselation
  • Cobra MKIII (source)
    * This C++ example demonstrates an interactive 3D mesh using the the GLU tesselator and per-pixel-lighting.
  • Primitives02(source)
    * This C++ example demonstrates simple polylines using the the GLU tesselator and per-pixel-lighting.
• Primitive Shader
  • SolInSpace(source)
    * Simple solar fragment-shader w/ core- and halo-radius.
• Simple Classics
  • Gears(source: rendering,input)
    * The infamous gears example, here with per-pixel-lighting and ray-cast AABBox selection.
  • RedSquare(source: rendering,input)
    * The mandatory most simple example.

Earlier Work

gfxbox2of our CS class evaluated the C++ to WebAssembly path earlier.

Status

This project is currently very much unstable and heavily_WIP_.

All APIs, if any, will change - but I thought it is nice to share the development with whoever might be interested.

TODO List

• Providing linear algebra and geometry in jaulib
• Windowing Toolkit (WT) abstraction w/ Surfaceand Window
• Basic OpenGLabstraction w/ GLProfile and GLcontext (bound to Surface)
• Event and listener (Window, Key, Pointer and Render)
  • RenderListener covers GLEventListenersemantics
• SDL2 based mainloop implementation for the above
  • Compatible with WebAssembly / emscripten
• OpenGLattribute array data objects for client and VBO server objects + interleaved sub-arrays
  • GLArrayData, …GLArrayDataServer<T>
• OpenGLuniform data objects
  • GLUniformData, …GLUniformSyncMatrices4f
• Shader support:ShaderCode, -Program,-State
  • Seamless shader file reading, configuration to match OpenGL profile
  • Shader state management: Shader switching and keeping attributes and uniforms in sync
    * Requires using above GLArrayData andGLUniformData
• Offscreen Surface /FBObject
• Shared OpenGLContext
  • Prepared, untested
• Primitive rendering API (poly-lines, circle/ball, boxes, textures)
  • Allow supporting simple applications like gfxbox2 utilizing Gamp
  • Enhance and test primitives, porting some gfxbox2 demos/games
• OpenAL Support
  • Add OO abstraction to simplify usage
• GraphUISupport
  • Basic Graph
  • TTF Font
  • FFMpeg video playback
  • GraphUIScenegraph
• Replace SDL2 withSDL3

API Documentation

C++ API documentation, with topics:

• Gamp
  • Windowing Toolkit
  • Graph
  • GL Rendering
  • GL Data
  • GL Shader
  • GL Implementation Details
• jaulib (standalone topics), excerpts:
  • Data Structures
  • File Utilities
  • Fraction Arithmetic and Time
  • Function Wrapper
  • IO Utilities
  • Math
    * Integer types and arithmetic
    * Float types and arithmetic
    * Constant Time (CT) Operations

Supported Platforms

• C++20 or better, see jaulib C++ Minimum Requirements.
• SDL2 library is supported
• emscripten for WebAssembly (optional)

Build Dependencies

• CMake >= 3.21 (2021-07-14)
• C++ compiler
  • gcc >= 11 (C++20), recommended >= 12.2.0
  • clang >= 13 (C++20), recommended >= 18.1.6
• Optional for lint validation
  • clang-tidy >= 18.1.6
• Optional for eclipse and vscodiumintegration
  • clangd >= 18.1.6
  • clang-tools >= 18.1.6
  • clang-format >= 18.1.6
• Optional
  • libunwind8 >= 1.2.1
  • libcurl4 >= 7.74 (tested, lower may work)
• jaulib submodule
• SDL2 library is supported
• emscripten for WebAssembly (optional)

Install on Debian or Ubuntu

Installing build dependencies for Debian >= 12 and Ubuntu >= 22:

apt install git
apt install build-essential g++ gcc libc-dev libpthread-stubs0-dev
apt install clang-18 clang-tidy-18 clangd-18 clang-tools-18 clang-format-18
apt install libunwind8 libunwind-dev
apt install cmake cmake-extras extra-cmake-modules pkg-config
apt install libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev libsdl2-mixer-dev
apt install doxygen graphviz
apt install emscripten

If using optional clang toolchain, perhaps change the clang version-suffix of above clang install line to the appropriate version.

After complete clang installation, you might want to setup the latest version as your default. For Debian you can use this clang alternatives setup script.

Build Procedure

Build preparations

git clone --recurse-submodules git://jausoft.com/srv/scm/gamp.git
cd gamp

CMake Build via Presets

Analog to jaulib CMake build presets …

Following debug presets are defined inCMakePresets.json

• debug
  • default generator
  • default compiler
  • C++20
  • debug enabled
  • disabled clang-tidy
• debug-gcc
  • inherits from debug
  • compiler: gcc
  • disabled clang-tidy
• debug-clang
  • inherits from debug
  • compiler: clang
  • enabled clang-tidy
• release
  • inherits from debug
  • debug disabled
  • disabled clang-tidy
• release-gcc
  • compiler: gcc
  • disabled clang-tidy
• release-clang
  • compiler: clang
  • enabled clang-tidy
• release-wasm
  • compiler: clang / emscripten
  • disabled clang-tidy
  • needs to be run by emcmake

Kick-off the workflow by e.g. using preset release-gccto configure, build, test, install and building documentation. You may skip install and doc by dropping it from--target.

cmake --preset release-gcc
cmake --build --preset release-gcc --parallel
cmake --build --preset release-gcc --target test install doc

You may utilize scripts/build-preset.sh for an initial build, install and test workflow.

CMake Build via Hardcoded Presets

Analog to jaulib CMake hardcoded presets …

Besides above CMakePresets.json presets,JaulibSetup.cmake contains hardcoded presets for_undefined variables_ if

• CMAKE_INSTALL_PREFIX andCMAKE_CXX_CLANG_TIDY cmake variables are unset, or
• JAU_CMAKE_ENFORCE_PRESETS cmake- or environment-variable is set to TRUE or ON

The hardcoded presets resemble debug-clang presets.

Kick-off the workflow to configure, build, test, install and building documentation. You may skip install and doc by dropping it from --target.

rm -rf build/default
cmake -B build/default
cmake --build build/default --parallel
cmake --build build/default --target test install doc

The install target of the last command will create the include/ and lib/ directories with a copy of the headers and library objects respectively in your dist location.

CMake Variables

Our cmake configure has a number of options, cmake-gui or_ccmake_ can show you all the options. The interesting ones are detailed below:

See jaulib CMake variables for details.

Unit Testing

TBD

Build Status

Will be updated

IDE Integration

Eclipse

Tested Eclipse 2024-03 (4.31).

IDE integration configuration files are provided for

• Eclipse with extensions
  • CDT or CDT @ eclipse.org
  • CDT-LSP recommended
    * Should work with clang toolchain >= 16
    * Utilizes clangd, clang-tidy and clang-format to support C++20 and above
    * Add to available software site:https://download.eclipse.org/tools/cdt/releases/cdt-lsp-latest
    * Install C/C++ LSP Support in theEclipse CDT LSP Category
  • CMake Support, installC/C++ CMake Build Support with IDorg.eclipse.cdt.cmake.feature.group
    * Usable via via Hardcoded CMake Presets with debug-clang

The Hardcoded CMake Presets will use build/default as the default build folder with debug enabled.

Make sure to set the environment variableCMAKE_BUILD_PARALLEL_LEVEL to a suitable high number, best to your CPU core count. This will enable parallel build with the IDE.

You can import the project to your workspace viaFile . Import... andExisting Projects into Workspace menu item.

For Eclipse one might need to adjust some setting in the.project and .cproject (CDT) via Eclipse settings UI, but it should just work out of the box.

Otherwise recreate the Eclipse project by

• delete .project and .cproject
• File . New . C/C++ Project andEmpty or Existing CMake Project while using this project folder.

VSCodium or VS Code

IDE integration configuration files are provided for

• VSCodium or VS Code with extensions
  • vscode-clangd
  • twxs.cmake
  • ms-vscode.cmake-tools
  • notskm.clang-tidy
  • cschlosser.doxdocgen
  • jerrygoyal.shortcut-menu-bar

For VSCodium one might copy the example root-workspace file to the parent folder of this project (note the filename change) and adjust the path to your filesystem.

cp .vscode/gamp.code-workspace_example ../gamp.code-workspace
vi ../gamp.code-workspace

Then you can open it viaFile . Open Workspace from File... menu item.

• All listed extensions are referenced in this workspace file to be installed via the IDE
• Select one of the CMake Presets for
  • Configuration
  • Build
  • Test

Gamp is lead by Gothel Software.

If you like to utilize Gamp in a commercial setting, please contact Gothel Software to setup a potential support contract or just help to fund the ongoing effort.

Common issues

Bugtracker etc to be setup at a later stage.

Changes

See Changes.