Pangolin Documentation

To render 3D content, you must map coordinates between different systems. Pangolin examples demonstrate how to handle:

• Normalized Device Coordinates (NDC): A coordinate system independent of resolution, typically ranging from -1.0 to 1.0 on the XY plane.
• Homogeneous Coordinates: Used to represent 4x4 linear transforms, which allows for perspective projection (which is non-linear) to be handled via matrix math.
• Coordinate Transforms: The process of converting your application's coordinate system into the system OpenGL expects.

To ensure all necessary submodules are included, use the --recursive flag when cloning the repository.

git clone --recursive https://github.com/stevenlovegrove/Pangolin.git

If you have built Sigslot from source, you can use the following CMake targets to build the included examples or run the unit tests:

• Examples: cmake --build . --target sigslot-examples
• Unit Tests: cmake --build . --target sigslot-tests

# If you want to compile examples:
cmake --build . --target sigslot-examples

# And compile/execute unit tests:
cmake --build . --target sigslot-tests

You can use the vcpkg dependency manager to install Pangolin.

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install pangolin

You can integrate Sigslot into your project using find_package. Link against the Pal::Sigslot target to ensure all compiler and linker requirements are met.

# Using Sigslot from cmake
find_package(PalSigslot)

add_executable(MyExe main.cpp)
target_link_libraries(MyExe PRIVATE Pal::Sigslot)

Pangolin uses a script to manage optional and required dependencies across various package managers (apt, brew, dnf, etc.). You can use the --dry-run flag to see recommended packages or specify a package manager and target (e.g., all) to install them.

# See what package manager and packages are recommended
./scripts/install_prerequisites.sh --dry-run recommended

# Override the package manager choice and install all packages
./scripts/install_prerequisites.sh -m brew all

Because C++ function pointers cannot uniquely identify overloads or handle default arguments automatically during connection, use these workarounds:

1. Overloaded Functions: Explicitly cast the function pointer using a helper like overload<Args>(...).
2. Default Arguments: Wrap the function in a lambda adapter (e.g., ADAPT(func)) to ensure the number of arguments passed by the signal matches the function signature.

Pangolin provides utilities to simplify shader management and improve readability compared to the standard GLSL workflow. Key features include:

• Preprocessor Support: Allows the use of #include, #expect, and #define within shader code.
• Multi-shader Files: You can load multiple shaders from a single file using @start annotations.
• C++ Wrappers: Provides wrappers to reduce the boilerplate typically associated with modern OpenGL shader pipelines.

You can compile Pangolin programs to run in a web browser using the Emscripten toolchain.

1. Install Emscripten SDK: Clone the emsdk repository, install the latest version, and activate it.
2. Build Pangolin: Create a dedicated build directory (e.g., build-em), source the Emscripten environment variables, and use emcmake to run CMake with the Emscripten toolchain settings.

# 1. Install Emscripten SDK
mkdir ~/tools && cd ~/tools
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk && ./emsdk install latest && ./emsdk activate latest

# 2. Build Pangolin with Emscripten
cd ~/code/Pangolin
mkdir build-em && cd build-em
source ~/tools/emsdk/emsdk_env.sh
emcmake cmake ..

To prevent calling slots on destroyed objects, Sigslot can automatically disconnect slots if the object's lifetime can be tracked.

• Supported out-of-the-box: std::shared_ptr, std::weak_ptr, boost::shared_ptr, boost::weak_ptr, and Qt types (QSharedPointer, QWeakPointer, and QObject derivatives).
• Custom types: Implement a to_weak() adapter function for your type.
• Intrusive tracking: Inherit from sigslot::observer (thread-safe) or sigslot::observer_st (non-thread-safe) to ensure automatic disconnection upon destruction.

#include <sigslot/signal.hpp>

// Intrusive approach
struct s : sigslot::observer_st {
    void f(int i) { /* ... */ }
};

int main() {
    sigslot::signal<int> sig;
    {
        s p;
        sig.connect(&s::f, &p);
    } // p is destroyed, sig automatically disconnects &s::f
    sig(1);
}

For projects that prefer to download dependencies during the CMake configuration step, use FetchContent to pull Sigslot directly from its repository.

include(FetchContent)

FetchContent_Declare(
  sigslot
  GIT_REPOSITORY https://github.com/palacaze/sigslot
  GIT_TAG        19a6f0f5ea11fc121fe67f81fd5e491f2d7a4637 # v1.2.0
)
FetchContent_MakeAvailable(sigslot)

add_executable(MyExe main.cpp)
target_link_libraries(MyExe PRIVATE Pal::Sigslot)