**Recommended Tools** _Instructions for the recommended [Graphics Codex Programming Project](../projects/index.html) toolset_ The Graphics Codex projects can be completed using any programming language, operating system, support code, and GPU. However, some are easier to use than others. I recommend the following, all-free software environment: - *C++* 11 - *OpenGL* 4.1 - *GLSL* 420 - *G3D* 10 - *SVN* 1.9 - *Doxygen* 1.8 - *Markdeep* 0.13 - *MSVC* 2017, or *clang++* 7.3 with Xcode 9.0 or Emacs 24 - *Very Sleepy* 0.9 profiler (on Windows) ...or later versions of these tools. This guide provides instructions for installing and using this environment for the projects on the *Windows*, *Linux*, and *OS X* operating systems. Because the tools are multiplatform, you can even switch between operating systems while working on a project. To use this recommended environment, you will need a computer with at least: - *64-bit* operating system - *64 GB* of free disk space - *4 GB* of RAM - *OpenGL 4.1*/*DirectX 11.1* GPU If you have a choice of OS and GPU, then I recommend *Windows 10* and an *NVIDIA 1060* or better GPU for reasons described in the following sections. Install Software ================================================================= If you already have your development machine, then just follow the following steps. 1. Purchase the [*Graphics Codex*](http://graphicscodex.com) for US$10 if you have not done so already, because all of the projects reference chapters and topics within it. 2. *Update your OS and drivers* 3. Install G3D: - If you're on Windows and don't mind a GUI installer, then run [the G3D installer](https://casual-effects.com/g3d/G3D10/installg3dwin.hta). You may have to wait a while without visual feedback while it is running, and if anything goes wrong, just reboot and run the same script again. It will pick up where it left off. - For other platforms: 1. *Install an IDE and C++ compiler* - Windows: Free [*Microsoft Visual Studio*](https://www.visualstudio.com/en-us/products/free-developer-offers-vs.aspx) 2017 Community Edition - OS X: Free [*Xcode*](https://itunes.apple.com/us/app/xcode/id497799835?mt=12), which includes clang++ - Linux: You may install [a Linux IDE](http://stackoverflow.com/questions/24109/c-ide-for-linux) if you wish; I prefer simple Emacs. clang++ should already be installed. 2. *Install Subversion* - Windows: Free [*TortoiseSVN*](https://tortoisesvn.net/). during installation, you must explcitly opt to *install the command-line tools* as well as the GUI (Figure [tortoissvn]). - OS X: Free command-line SVN via the [MacPorts](https://www.macports.org/) command "`sudo port install subversion`", or GUI [*Snail SVN*](https://langui.net/snailsvn/) - Linux: Command-line SVN is built in 3. [*Install the G3D Innovation Engine*](https://casual-effects.com/g3d/www/index.html#install). Note that the G3D install process includes *Doxygen* and *Python* installations and environment variable configuration. 4. Be sure to set your `G3D10DATA` environment variable as described in the [G3D build instructions](https://casual-effects.com/g3d/G3D10/readme.md.html). if you haven't already. Forgetting to set this environment variable is the #1 source of problems for programmers new to G3D. 4. *Reboot*, or at least log out and then back in, to ensure that your environment variable changes have all been reflected. 5. As described in the sections below, follow the configuration instructions for your chosen IDE then compiling and run the G3D Starter project in `G3D10/samples/starter` to test your environment. [*Markdeep*](https://casual-effects.com/markdeep/) automatically runs within a web browser with an internet connection and does not require any installation. If you plan to develop offline, then you can download the latest `markdeep.min.js` and store it with each of your projects for formatting your journal and report. You can of course use another version control tool, such as git, for your own projects. I recommend Subversion because you need it anyway to install G3D, and G3D provides special support for documenting your projects when you use Subversion. On Windows, I recommend and frequently use the free [*Very Sleepy*](http://www.codersnotes.com/sleepy/) profiler. NVIDIA's free [*Nsight*](https://developer.nvidia.com/nsight-visual-studio-edition-3_0-new-features) for Visual Studio supports OpenGL profiling and debugging, but I find I only need it occasionally because G3D's GPU tools are often good enough on their own. ![Figure [tortoissvn]: TortoiseSVN installation dialog option to add command-line tools on windows. These are needed for G3D's svn integration on that platform.](tortoisesvn.png) Choose a GPU ================================================================= _Summary: If you can, buy a Max-Q gaming laptop or put the latest midrange NVIDIA RTX GPU in your desktop computer. Skip this section if you have already chosen your GPU._ The Graphics Processing Unit (GPU) is an embedded processor or PCI expansion card inside of your computer for accelerating 3D graphics. Low-end desktops and midrange laptops use Intel embedded GPUs. Development stations and high-end laptops use discrete GPUs by AMD and NVIDIA. Unlike CPUs, not all programs will run on all GPUs. You need a relatively recent (last few years) GPU to handle modern graphics programming. An old GPU won't just be slow--it won't even work in many cases. The GPU is managed by the driver software. This is like an operating system for the GPU, except that it is invisible to normal users. Vendors update their driver software roughly once a month, and it is important to have the latest version. That will reduce GPU malfunctions due to driver errors, which are relatively common compared to CPU operating system bugs. In general, the most stable drivers are currently available on *Windows*, and *NVIDIA*'s driver support is the best among all vendors. On MacOS, the OpenGL drivers are provided by Apple and are currently about five years out of date for all GPUs. Simply rebooting an OS X machine to Windows dramatically improves its graphics capabilities using the same hardware. NVIDIA laptop and desktop drivers are identical. AMD can't currently update their laptop drivers at all, so on a laptop you should definitely prefer an NVIDIA GPU. ## Best Value When estimating the processing power of a processor, multiply the number of cores by the clock speed. Obviously, newer architectures also add some performance advantages beyond this. The key difference for a graphics course is ray tracing performance. NVIDIA RTX GPUs currently offer 10x the ray tracing performance of other graphics cards, so As of 2019, the [NVIDIA GeForce RTX 2060](https://www.amazon.com/s?k=geforce+2060) provides the best ratio of performance to price by this metric for general 3D development. It costs about US$370. The GeForce RTX 1060 is a reasonable second choice at US$200, although it falls far behind in ray tracing performance. Both of these GPUs are also good for *virtual reality* development. ## Enthusiast GPUs A high-end GPU isn't necessary, but it makes graphics programming even more fun. It allows you to render at higher resolutions, move more smoothly through your scenes, and wait less time for your programs to execute. High-end GPUs are a little different from midrange equipment and you should know a few things before getting one. Here's some advice if you're in a position to do so. For graphics development, it is better to buy a newer architecture than faster-but-older GPU at the same price. A newer GPU ensures the best driver support and access to the latest features, which both make programming easier and create disproportionate speedups. As of 2019, there is only one choice for peak graphics performance: [NVIDIA GeForce RTX 2080 Ti](https://amzn.to/2tPzA9C). It is substantially faster than every other GPU in its US$1250 price range for ray tracing, rasterization graphics, and machine learning. Multi-GPU programming (via SLI and Crossfire) is difficult and poorly supported by GPU drivers. So, for development, it is better to buy one powerful GPU than two weaker GPUs. Even on computers with multiple powerful GPUs, I rarely try use more than one in my own software. Beware that high-end GPUs draw a lot of power and take up a lot of space. You may need a 500W or even 800W power supply, large PCI slot, and room inside of the case. You may also need a monitor with the latest connections (currently display port), or cables and adapters. As with sports cars, the performance-to-price tradeoff at the highest end of the market is extreme and well past the point of diminishing returns. The most practical development GPU is usually one or two models below the flagship high-end card in a series from a vendor, outfitted with 6 GB or more video RAM. The best mobile GPU in a series usually has only a fraction of the power of the best desktop GPU in that series. Gaming laptops often contain _desktop_ GPUs in them. Likewise, beware that some desktops (such as the iMac) use _mobile_ GPUs and may not be as powerful as they sound. You want a gamer card. You do _not_ need a Quadro, Tesla, or FirePro GPU. Those professional GPUs are very expensive and designed for applications that prioritize reliability over performance. ## Budget GPUs  The *NVIDIA GeForce 700*, *AMD Radeon HD 7700*, and *AMD Radeon R7* series are the lowest that I would consider for graphics development today. These cost about US$40. Technically, some slightly lower GPUs will also support OpenGL 4.2, but they are built on different chipsets and are likely to have less well-tested drivers. If you don't have access to a discrete GPU, then you can run graphics on a recent Intel embedded GPU (Haswell or later). However, the performance will be low compared to a discrete GPU and Intel's drivers are not as good as those for discrete GPUs. ## Software Emulation You can emulate a GPU's functionality entirely on the CPU using a software library such as [Mesa3D](http://www.mesa3d.org/). However, that is extremely slow (and doesn't meet G3D's minimum spec of GL4.1) and will limit your ability to debug effectively on the more advanced projects. I do not recommend this. Choose an OS ====================================================================== _Summary: If you can choose your OS, prefer Windows 8.1 or later. It has the best graphics drivers, sound drivers, and development tools. Skip this section if you have already chosen your OS._ The recommended Graphics Codex Project tools work on Windows, Linux, and OS X. *Windows* offers the best software development environment, with lots of GUI tools (MSVC, VerySleepy, VTune, etc), audio/video support, and media-editing software (such as Photoshop and Premiere). *OS X* has OpenGL driver limitations but otherwise provides reasonable GUI tools (such as XCode), great A/V support, and most of the same media packages as on Windows. *Linux* has relatively poor GUI tools for development, pretty good OpenGL drivers, and poor A/V support. Graphics development does not work well in a virtual machine such as Parallels or Xen because you need low-level access to the CPU and GPU. If you have a non-Windows computer and would like to run Windows, then I recommend using one of the following strategies. Dual Booting --------------------------------------------------------------- On a Mac, the [*Boot Camp*](https://www.apple.com/support/bootcamp/) software allows painless installation of Windows and OS X side-by-side on the same machine. I've used this for graphics development on my own MacBook Pros for years. For a Ubuntu Linux PC, you can first install Windows and then install a second operating system using [these instructions](http://www.linuxandubuntu.com/home/dual-boot-ubuntu-15-04-14-10-and-windows-10-8-1-8-step-by-step-tutorial-with-screenshots). Bootable USB Disk ------------------------------------------------------------- [*Windows To Go*](https://www.microsoft.com/en-us/download/details.aspx?id=48127) is a feature of Windows 10 and Windows 8.1 Enterprise editions that allows you to create fully bootable USB disks.  Using this feature, you can produce a complete development installation on a USB disk. By pluggin that USB disk into a computer and rebooting it, you can temporarily take the machine over as a Windows development station without modifying the computer's hard drive. This is the method that I use for my current college course, because it allows students to move between machines without copying files across the network and avoids having to modify the installation of the lab computers. To use Windows To Go, you need a certified disk. Uncertified USB disks will not boot the operating system without being hacked. It is also important to have a high-bandwidth disk when using it as the main drive for an OS, and the certified disks are all fast enough. While the physically tiny keychain drives are more expensive per gigabyte, a certified [500GB Passport USB](http://amzn.to/2aoJfuP) drive currently costs less than US$100. You need at least a 128 GB disk in order to have 64 GB free for development after installing the operating system. That 64 GB includes (conservatively) the space for all of the projects you're going to create...you will initially require much less. Configure the Editor ========================================================================= _This section explains how to configure Visual Studio on Windows and Emacs on all platforms. Skip it if you are using another editor. This does not include configuring the build system as described in the G3D installation instructions._ Indentation ------------------------------------------------------------------------- My coding conventions use four-space indenting and no tabs. If you're working with someone else or in a course, then I highly recommend configuring your editor to follow this. It avoids merge conflicts over whitespace and ensures that your code looks the same to everyone (instead of randomly indented). Although slightly annoying, differing standards for where to put braces and spaces within lines aren't as disruptive as differing standards for indentation, which really make code unreadable when tabs are processed differently. In *Visual Studio*, you can set indenting to four spaces from Tools ==> Options ==> Text Editor ==> C/C++ ==> Tabs as shown in Figure [msvcIndent]. ![Figure [msvcIndent]: Visual Studio intendentation configuration.](msvc-indent.png) In *Emacs*, put the code from Listing [emacsTabs] anywwhere in your `~/.emacs` file to ensure four-space indenting with no tabs. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ; Four-space indentation with no tabs (setq-default indent-tabs-mode nil) (setq tab-width 4) (setq c-basic-offset 4) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [Listing [emacsTabs]: Emacs configuration for indentation.] Shader Editing ------------------------------------------------------------------------- To enable syntax highlighting in *Visual Studio*, at Tools ==> Options ==> Text Editor ==> File Extensions, associate the following (one at a time) with "Microsoft Visual C++": `any`, `vrt`, `pix`, `geo`, `glsl` as shown in Figure [msvcExtension]. ![Figure [msvcExtension]: Visual Studio syntax highighting configuration.](msvc-extension.png) In *Emacs*, add the code from Listing [emacsHighlight] anywhere in your `~/.emacs` file. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ; OpenGL and G3D files (setq auto-mode-alist (append '(("\\.any$" . c++-mode) ("\\.vrt$" . c++-mode) ("\\.pix$" . c++-mode) ("\\.geo$" . c++-mode) ("\\.glsl$" . c++-mode)) auto-mode-alist)) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [Listing [emacsHighlight]: Emacs configuration for shader syntax highlighting] Markdeep Editing ------------------------------------------------------------------------- [Markdeep](https://casual-effects.com/markdeep/) is an extension of markdown that runs locally and automatically in a web browser. It is based on the technology used to implement the Graphics Codex itself (and is what I used to create this Tools document!) G3D has special support for helping you maintain a development journal in Markdeep format, including screenshots and videos. If you're writing the project lab reports, I recommend using Markdeep for those as well. *Visual Studio* strangely has no "plain text" editing mode and the built-in and currently available markdown extensions don't work well for Markdeep's advanced features. Fortunately, Markdeep documents have extensions of `.html`, so Visual Studio automatically uses its HTML editor for them and this works pretty well. I recommend disabling all of the options that automatically insert and modify your HTML/Markdeep code. In Tools ==> Options ==> Text Editor ==> HTML, change your options to match Figure [fig:msvchtml]. ![Figure [fig:msvchtml]: Preferred options for Visual Studio HTML mode.](msvc-html.png) For *Emacs*, you can install [Emacs Markdown Mode](http://jblevins.org/projects/markdown-mode/) and then configure your `~/.emacs` file as shown in Listing [emacsMarkdown]. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ; Markdown mode (autoload 'markdown-mode "markdown-mode" "Major mode for editing Markdown files" t) (add-to-list 'auto-mode-alist '("\\.md.html\\'" . markdown-mode)) (add-to-list 'auto-mode-alist '("\\.md\\'" . markdown-mode)) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [Listing [emacsMarkdown]: Emacs configuration for editing Markdeep files.] Other Frameworks =============================================================================== Before I decided on the G3D/C++ toolset for the Graphics Codex, I researched several other platforms and frameworks. Here are some of my notes on those if you'd like to explore alternatives. Beware that these alternatives generally lack the full feature set of G3D in combining ray tracing, GPU rendering, scene modeling, research features, and built-in developer tools. Javascript ("WebGL") : Use [three.js](http://threejs.org/) for OpenGL abstraction and [bvh-tree](https://github.com/benraziel/bvh-tree) for the BVH on ray tracing projects. Directly use the [web audio](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) and [web gamepad](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad) APIs for interaction projects. [Cannon.js](http://www.cannonjs.org/) for 3D physics. [Socket.IO](http://socket.io/) for networking. Python : [PyGame](http://www.pygame.org/hifi.html) for OpenGL, events, and audio. [PyEnet](https://github.com/aresch/pyenet) for networking. [PyODE](http://pyode.sourceforge.net/) for 3D physics. Java : Use the built-in Oracle [j3d](http://www.oracle.com/technetwork/articles/javase/index-jsp-138252.html) library that includes 3D model loading, or [JOGL](http://jogamp.org/jogl/www/) for standard OpenGL bindings. Various libraries provide physics, networking, gamepad support, etc. C# : Use [Unity](http://unity3d.com) for all components, or [OpenTK](https://github.com/opentk/opentk) for OpenGL and audio and [BulletSharp](https://andrestraks.github.io/BulletSharp/) for 3D physics. The standard library already handles networking and gamepads. You'll need a bounding volume hierarchy for the advanced ray tracing projects, such as [this one](https://github.com/jeske/SimpleScene/tree/master/SimpleScene/Util/ssBVH). Rust : [GLium](https://github.com/tomaka/glium) provides OpenGL bindings and [nphysics](https://github.com/sebcrozet/nphysics) is a 3D physics library. There are several immature game engines that you can explore for 3D event handling. [tray_rust](https://github.com/Twinklebear/tray_rust) might be a good basis for the BVH and helper routines. If you're willing to forgo real-time rendering and GUI tools, you can experiment with the ray tracing projects on top of [Mitsuba](https://www.mitsuba-renderer.org/) or [PBRT](https://github.com/mmp/pbrt-v3). Since those _are_ fully-functional path tracers, you'll have to replace their components (which they are designed for) with comparable ones written by yourself in each projet. The [Unity](http://unity3d.com/), [Unreal](https://www.unrealengine.com/what-is-unreal-engine-4), [Lumberyard](https://aws.amazon.com/lumberyard/), and [CryEngine](https://www.cryengine.com/) game engines provide sophisticated developer tools and artist pipelines. Because of that and their multiplatform support, these are attractive options for learning graphics. The challenge is that game enginers make it hard to radically change the renderer. They also generally don't support ray tracing well at all. That said, I've been very pleased with how easy Unity is to learn and work with in particular. In any of these engines, you _can_ leverage the physics system for ray casting, albeit at about 1/100th the performance of G3D's high-performance `TriTree` class.