<commit_before>## Gfx Module

The Oryol Gfx module provides a thin portability wrapper around the 
native 3D APIs of a target platform, with WebGL/OpenGLES2 on the low-end, and
D3D12 and (hopefully soon) Vulkan on the 'high-end'.

### Platform/API matrix

What 3D APIs are supported on which platforms:

Platform   |GL3.3|GLES2|Metal|D3D11|D3D12|Vulkan
-----------|-----|-----|-----|-----|-----|------
OSX 10.11+ |YES  |---  |YES  |---  |---  |---
iOS 9.x+   |---  |YES  |YES  |---  |---  |---
Window7+   |YES  |---  |---  |YES  |---  |MAYBE
Window10+  |YES  |---  |---  |YES  |YES  |MAYBE
Linux      |YES  |---  |---  |---  |---  |MAYBE
Android    |---  |YES  |---  |---  |---  |MAYBE
HTML5      |---  |YES  |---  |---  |---  |---
PNaCl      |---  |YES  |---  |---  |---  |---
RaspberryPi|---  |YES  |---  |---  |---  |---

### Use the Source, Luke!

The most important and detailed documentation of the Gfx module
is the Samples source code. I'm trying very hard to make
the sample code easy to read and understand.

Looking at those four samples should give you most of the
information necessary to work with the Gfx module:

* [Clear Sample](https://github.com/floooh/oryol/blob/master/code/Samples/Clear/Clear.cc)
* [Triangle Sample](https://github.com/floooh/oryol/blob/master/code/Samples/Triangle/Triangle.cc)
* [Shapes Sample](https://github.com/floooh/oryol/blob/master/code/Samples/Shapes/Shapes.cc)
* [Texture Loading](https://github.com/floooh/oryol/blob/master/code/Samples/DDSCubeMap/DDSCubeMap.cc)
* [Offscreen Render Targets](https://github.com/floooh/oryol/blob/master/code/Samples/SimpleRenderTarget/SimpleRenderTarget.cc)

The 'manual' documentation in here will focus more on 'filling the gaps',
background information and explaining design choices.

### Selecting a Rendering Backend

Rendering backends are selected at compile time through cmake options and
cannot be switched at runtime. Each target platform has a default rendering
backend that will be selected automatically, usually this is OpenGL.

The easiest way to select a non-default rendering backend is to
select a different **fips build config**:

To see the list of supported build configs for D3D11, D3D12 
and Metal:

```
> ./fips list configs | grep d3d11
...
> ./fips list configs | grep d3d12
...
> ./fips list configs | grep metal
...
```

For instance, to select an iOS build config using the Metal rendering backend:

```
> ./fips set config metal-ios-xcode-debug
'config' set to 'metal-ios-xcode-debug' in project 'oryol'
> ./fips gen
...
> ./fips open
...
```

Alternatively, the rendering backend can be selected by activating
cmake options directly in the cmake config tool:

```bash
> fips config
...
# the cmake options are:

ORYOL_USE_D3D11
ORYOL_USE_D3D12
ORYOL_USE_METAL
```

### Optional Gfx Features

For some Gfx features, a runtime check must be performed before they can be
used. Call the method **Gfx::QueryFeature()** with one of the following:

* **GfxFeature::TextureCompressionDXT**: check if DXT texture compression
support is available, DXT is supported on all desktop GPUs, but not on most 
mobile GPUs
* **GfxFeature::TextureCompressionPVRTC**: check if the PowerVR PVRTC 
texture compression format is supported, this is the most popular 
texture compression scheme on iOS devices
* **GfxFeature::TextureCompressionATC**: check if the ATC texture compression
format is supported (Adreno GPUs)
* **GfxFeature::TextureCompressionETC2**: check if the ETC2 texture 
compression format is supported
* **GfxFeature::TextureFloat**: check if floating point texture are supported for
sampling and as render target
* **GfxFeature::TextureHalfFloat**: check if half-float textures are supported
for sampling
* **GfxFeature::Instancing**: check if D3D9-style hardware-instanced rendering
is supported
* **GfxFeature::OriginBottomLeft**: the image-space origin is 
bottom-left (GL style)
* **GfxFeature::OriginTopLeft**: the image-space origin is
top-left (D3D style)

### Frame Rendering

Rendering through the Gfx module usually involves the following steps:

1. [Initialize the Gfx Module](#initialize-the-gfx-module)
2. [Create Resources](#resources)
3. [Apply Render Target and optionally Clear](#render-targets)
4. [Optional: Update Dynamic Resources](#dynamic-resources)
5. [Apply a DrawState and Textures](#drawstates)
6. [Apply Uniform Blocks](#uniformblocks)
7. [Draw](#draw-functions)
8. [Commit](#committing-the-frame)
9. [Shutdown the Gfx Module](#shutting-down)

### Initialize the Gfx Module

To initialize the Gfx module, include the header **"Gfx/Gfx.h"** and
call the **Gfx::Setup()** method. This will create the application window
and a 3D-API context:

```cpp
#include "Gfx/Gfx.h"
...
    Gfx::Setup(GfxSetup::Window(800, 600, "My Oryol App"));
```
This would create a 800x600 window titled "My Oryol App".

The GfxSetup object allows to configure and tweak the rendering system
for the specific needs of the Oryol application. Have a look at the
[Gfx/Gfx.h](https://github.com/floooh/oryol/blob/master/code/Modules/Gfx/Setup/GfxSetup.h)
header to see what's possible.

>NOTE: On some platforms (mostly mobile), the actual rendering 
resolution can be different from what the application requested. To
get the actual rendering resolution, call the **Gfx::DisplayAttrs()** method after
the Gfx module has been initialized.

See also:
- [GfxSetup.h](https://github.com/floooh/oryol/blob/master/code/Modules/Gfx/Setup/GfxSetup.h)
- [Gfx.h](https://github.com/floooh/oryol/blob/master/code/Modules/Gfx/Gfx.h)

### Resources

Gfx resources are thin wrapper objects which manage the lifetime of an
underlying 3D-API-specific rendering resource.

See also:
- [Resource Module](https://github.com/floooh/oryol/blob/master/code/Modules/Resource/README.md)<commit_msg>Minor typo fix in Gfx/README.md<commit_after>## Gfx Module

The Oryol Gfx module provides a thin portability wrapper around the 
native 3D APIs of a target platform, with WebGL/OpenGLES2 on the low-end, and
D3D12 and (hopefully soon) Vulkan on the 'high-end'.

### Platform/API matrix

What 3D APIs are supported on which platforms:

Platform   |GL3.3|GLES2|Metal|D3D11|D3D12|Vulkan
-----------|-----|-----|-----|-----|-----|------
OSX 10.11+ |YES  |---  |YES  |---  |---  |---
iOS 9.x+   |---  |YES  |YES  |---  |---  |---
Window7+   |YES  |---  |---  |YES  |---  |MAYBE
Window10+  |YES  |---  |---  |YES  |YES  |MAYBE
Linux      |YES  |---  |---  |---  |---  |MAYBE
Android    |---  |YES  |---  |---  |---  |MAYBE
HTML5      |---  |YES  |---  |---  |---  |---
PNaCl      |---  |YES  |---  |---  |---  |---
RaspberryPi|---  |YES  |---  |---  |---  |---

### Use the Source, Luke!

The most important and detailed documentation of the Gfx module
is the Samples source code. I'm trying very hard to make
the sample code easy to read and understand.

Looking at those four samples should give you most of the
information necessary to work with the Gfx module:

* [Clear Sample](https://github.com/floooh/oryol/blob/master/code/Samples/Clear/Clear.cc)
* [Triangle Sample](https://github.com/floooh/oryol/blob/master/code/Samples/Triangle/Triangle.cc)
* [Shapes Sample](https://github.com/floooh/oryol/blob/master/code/Samples/Shapes/Shapes.cc)
* [Texture Loading](https://github.com/floooh/oryol/blob/master/code/Samples/DDSCubeMap/DDSCubeMap.cc)
* [Offscreen Render Targets](https://github.com/floooh/oryol/blob/master/code/Samples/SimpleRenderTarget/SimpleRenderTarget.cc)

The 'manual' documentation in here will focus more on 'filling the gaps',
background information and explaining design choices.

### Selecting a Rendering Backend

Rendering backends are selected at compile time through cmake options and
cannot be switched at runtime. Each target platform has a default rendering
backend that will be selected automatically, usually this is OpenGL.

The easiest way to select a non-default rendering backend is to
select a different **fips build config**:

To see the list of supported build configs for D3D11, D3D12 
and Metal:

```
> ./fips list configs | grep d3d11
...
> ./fips list configs | grep d3d12
...
> ./fips list configs | grep metal
...
```

For instance, to select an iOS build config using the Metal rendering backend:

```
> ./fips set config metal-ios-xcode-debug
'config' set to 'metal-ios-xcode-debug' in project 'oryol'
> ./fips gen
...
> ./fips open
...
```

Alternatively, the rendering backend can be selected by activating
cmake options directly in the cmake config tool:

```bash
> fips config
...
# the cmake options are:

ORYOL_USE_D3D11
ORYOL_USE_D3D12
ORYOL_USE_METAL
```

### Optional Gfx Features

For some Gfx features, a runtime check must be performed before they can be
used. Call the method **Gfx::QueryFeature()** with one of the following:

* **GfxFeature::TextureCompressionDXT**: check if DXT texture compression
support is available, DXT is supported on all desktop GPUs, but not on most 
mobile GPUs
* **GfxFeature::TextureCompressionPVRTC**: check if the PowerVR PVRTC 
texture compression format is supported, this is the most popular 
texture compression scheme on iOS devices
* **GfxFeature::TextureCompressionATC**: check if the ATC texture compression
format is supported (Adreno GPUs)
* **GfxFeature::TextureCompressionETC2**: check if the ETC2 texture 
compression format is supported
* **GfxFeature::TextureFloat**: check if floating point texture are supported for
sampling and as render target
* **GfxFeature::TextureHalfFloat**: check if half-float textures are supported
for sampling
* **GfxFeature::Instancing**: check if D3D9-style hardware-instanced rendering
is supported
* **GfxFeature::OriginBottomLeft**: the image-space origin is 
bottom-left (GL style)
* **GfxFeature::OriginTopLeft**: the image-space origin is
top-left (D3D style)

### Frame Rendering

Rendering through the Gfx module usually involves the following steps:

1. [Initialize the Gfx Module](#initialize-the-gfx-module)
2. [Create Resources](#resources)
3. [Apply Render Target and optionally Clear](#render-targets)
4. [Optional: Update Dynamic Resources](#dynamic-resources)
5. [Apply a DrawState and Textures](#drawstates)
6. [Apply Uniform Blocks](#uniformblocks)
7. [Draw](#draw-functions)
8. [Commit](#committing-the-frame)
9. [Shutdown the Gfx Module](#shutting-down)

### Initialize the Gfx Module

To initialize the Gfx module, include the header **"Gfx/Gfx.h"** and
call the **Gfx::Setup()** method. This will create the application window
and a 3D-API context:

```cpp
#include "Gfx/Gfx.h"
...
    Gfx::Setup(GfxSetup::Window(800, 600, "My Oryol App"));
```
This would create a 800x600 window titled "My Oryol App".

The GfxSetup object allows to configure and tweak the rendering system
for the specific needs of the Oryol application. Have a look at the
[Gfx/GfxSetup.h](https://github.com/floooh/oryol/blob/master/code/Modules/Gfx/Setup/GfxSetup.h)
header to see what's possible.

>NOTE: On some platforms (mostly mobile), the actual rendering 
resolution can be different from what the application requested. To
get the actual rendering resolution, call the **Gfx::DisplayAttrs()** method after
the Gfx module has been initialized.

See also:
- [GfxSetup.h](https://github.com/floooh/oryol/blob/master/code/Modules/Gfx/Setup/GfxSetup.h)
- [Gfx.h](https://github.com/floooh/oryol/blob/master/code/Modules/Gfx/Gfx.h)

### Resources

Gfx resources are thin wrapper objects which manage the lifetime of an
underlying 3D-API-specific rendering resource.

See also:
- [Resource Module](https://github.com/floooh/oryol/blob/master/code/Modules/Resource/README.md)
{'fraction_non_alphanumeric': 0.1321259163432514, 'fraction_numerical': 0.01207416990081932, 'mean_word_length': 3.8990283058724122, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 19, 'https://': 18, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2456894', 'n_tokens_mistral': 3828, 'n_tokens_neox': 3624, 'n_words': 1247}