Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

Welcome to Asdf Overlay. Asdf Overlay provides an easy to use interface to draw on top of windows. It is primarily targeting games, but it can be used on any programs using GPU.

  1. Automatic graphics backend detection
  2. GPU accelerated shared overlay surface
  3. Input passthrough control

Example image

By reading the documentation you will learn how to

  1. Setup development environment and building the library
  2. Position overlay surface in multiple way
  3. Control input passthrough

Supported graphics backend

  • OpenGL
  • DX9
  • DX10
  • DX11
  • DX12
  • Vulkan (via loading as vulkan layer)

License

This project is dual licensed under MIT or Apache-2.0 License.

Prerequirements

To build Asdf Overlay, you need prerequirements. Click each items below, follow the install instructions.

Workspace Setup

To setup Asdf Overlay workspace, you will first need to clone the repository.

Following command can be used to clone Github repository.

git clone https://github.com/storycraft/asdf-overlay

After cloning repository, change the current directory.

cd asdf-overlay

Initialize and update submodules by using a command below.

git submodule update --init --recursive

Finish by installing node dependencies.

pnpm install

Building project

Once you done set up workspace, you can build the project using following command.

pnpm build

For more detail, see Pnpm Command - build.

Debugging

By default, release build will not emit any logs due to performance overhead. To debug overlay DLL, you need to build with debug profile.

To build overlay DLL with debug profile, following command can be used.

pnpm build-dll

After building, replace overlay DLL. Overlay DLL with debug profile will emit tracing to Debug Output Window. Use external debug log viewer (ex: DebugView) to see debug output.

Installation

Asdf Overlay is distributed as Rust crate and Node.js package. Follow the relevant sections.

Node.js Package

Following command can be used to install Node.js package

npm add asdf-overlay-node

Rust crate

Following command can be used to install Rust crate

cargo add asdf-overlay-client

Concepts

To expose consistent interface from the target process, the library introduces some concepts. These concepts are important as they represents how Asdf Overlay hook and abstracts underlying rendering infrastructure.

Window

Each window can accept inputs and have one surface associated to a swapchain.

Swapchain

Swapchain represents collection of framebuffers associated to an window. The actual implementation varies by GPU backends.

For each swapchain, Asdf Overlay accept any BGRA formatted Direct3D 11 shared texture to be set as overlay surface. Provided Direct3D 11 texture is drew on top of actual framebuffer before presentation.

Overlay texture must be drew using same GPU with target swapchain as it uses shared texture to avoid expensive cpu copy. If provided texture is rendered on other GPU, the rendering will fail and overlay will not be displayed. This is not significant issue on desktop as most desktops have only one GPU. However some laptops have integrated GPU and discrete one then it can be problem.

Input

Input is mouse and keyboard inputs coming from window. This also includes raw inputs coming from event loop associated to a window.

Asdf Overlay let you listen these inputs, intercept and block them so users can interact with overlay. To prevent abuse, blocking is disabled when the user attempts to close the window.