Quake Capture: How to patch an engine

(If you just want to run the default engine with capture rather than patching the functionality into a particular engine modification, you can find precompiled versions of quake1capture and quake2capture on the project home page. If you have one of these, you can proceed to instructions on using capture.)

The same download works to patch either engine. (If you haven't already downloaded it, please see the project home page.)

Patching the two engines is similar. You unzip a set of new files, and add the appropriate ones to your Quake1/2 project. Then you apply a small set of diffs to a few existing files of your modified engine. See the engine-specific instructions for Quake1 and Quake2 below. If your mod has substantially changed certain parts of the engine, you may wish also to read the developer notes, but usually you can proceed in blissful blackbox ignorance.

For AVI capture, you will need vfw32.h to compile, and avifil32.dll et al to run. I understand these to be available as standard on development and user Win32 platforms respectively.

Instructions for patching a Quake1 engine

1. Unzip into the 'YourQuakeMod/WinQuake/' source directory. (Files will be placed in a 'capture/' subdirectory.)
2. Open your WinQuake.dsw Microsoft Visual Studio workspace, and add the following to your winquake files.
   (Not using MSVC++? I'll assume you know what you're doing. Add them to the appropriate makefile or equivalent for your build environment.)
   • patch.c
   • helpers_q1.c
   • bridge.cpp
   • AviWriter.cpp
   • ScreenShotWriter.cpp
   You may also want to add the referenced header files:
   • patch.h
   • helpers.h
   • bridge.h
   • IWriter.h
   • AviWriter.h
   • ScreenShotWriter.h
   These files are only for Quake2 and should be ignored:
   • helpers_q2.c
   • gl_copypixels_backdoor.h
3. Now you need to apply some small changes to files in your existing engine.
   The changes are available as diffs to the original id1 codebase in the project CVS repository. If you follow each of the links below, you'll see part(s) of the original id1 file on the left, and on the right the same part(s) of the file after changes. There are further options to display the change in other ways available on the dropdown menu. All of the changes involve adding a few lines at particular points in the files, and you should be able to add the same lines at the corresponding points in the files in your modified engine.
   • cl_demo.c
   • cl_main.c
   • client.h
   • gl_screen.c
   • snd_dma.c
   • snd_mix.c
   For slightly less friendly offline reference, here is a text copy of the same changes as a context diff.

Instructions for patching a Quake2 engine

1. Unzip into the 'YourQuake2Mod/' source directory. (Files will be placed in a 'capture/' subdirectory.)
2. Open your quake2.dsw Microsoft Visual Studio workspace, and add the following to your quake2 files.
   (Not using MSVC++? I'll assume you know what you're doing. Add them to the appropriate makefile or equivalent for your build environment.)
   • patch.c
   • helpers_q2.c
   • bridge.cpp
   • AviWriter.cpp
   • ScreenShotWriter.cpp
   You may also want to add the referenced header files:
   • patch.h
   • helpers.h
   • bridge.h
   • gl_copypixels_backdoor.h
   • IWriter.h
   • AviWriter.h
   • ScreenShotWriter.h
   This files is only for Quake1 and should be ignored:
   • helpers_q1.c
3. Now you need to apply some small changes to files in your existing engine.
   The changes are available as diffs to the original id1 codebase in the project CVS repository. If you follow each of the links below, you'll see part(s) of the original id1 file on the left, and on the right the same part(s) of the file after changes. There are further options to display the change in other ways available on the dropdown menu. All of the changes involve adding a few lines at particular points in the files, and you should be able to add the same lines at the corresponding points in the files in your modified engine.
   • cl_main.c
   • cl_scrn.c
   • client.h
   • snd_dma.c
   • snd_mix.c
   • common.c
   • gl_rmain.c (this last file is in the gl_ref project)
   For slightly less friendly offline reference, here is a text copy of the same changes as a context diff.

Developer notes

My intent is that this patch should be as easy as possible to apply to existing engine mods, and that also it can be maintained and extended further if desired. The architecture was designed with that in mind. Please do let me know if you have success or otherwise in patching your favourite engine mods!

The patch code touches engines directly in as few places as possible. The patch.h interface is narrow and you only have to call out to it from your code in a few places.

The patch.c itself works with both Quake1 and Quake2. It uses the interface defined in helpers.h in the places where engine-specific code is necessary. helpers_q1.c and helpers_q2.c hold this engine-specific implementation. In the relatively unlikely event that you've altered something fundamental in the engine that proves relevant, you should compensate by changing the relevant helpers.c.

(It is possible that the patch could be adapted to further GPLed game engines if and when they appear, but there would need to be some further movement of stuff from patch to helpers. Let's see how it goes.)

Note that the Quake2 version makes use of a console command backdoor to allow it to extract video data from the separate ref_gl renderer without having to change the API to that library. Not code to be proud of, but at least it should not interfere with any existing mod-specific API extensions or version number changes.

The capture machinery itself is written in C++. The bridge.h and bridge.cpp act as an adapter/bridge between the C-coded Quake engine and the C++-coded capture machinery. It also implements a factory method to create the relevant kind of capture writer depending on the capture mode.

There is also the intent that it should be simple to add further capture modes if desired. To help this capture writing is encapsulated in an IWriter interface class. The original and probably most useful form of capture implemented is AviWriter. I also added the ScreenShotWriter class as proof of principle that further modes could be implemented, and to give something to non-Win32 platforms. If anyone wants to help implement further writers, let me know.