Skip to content

Commit 42c2a09

Browse files
jbritainjbritain
authored
Merge pull request #367 from IrisShaders/feat/prioritise-compatibility-profile
feat: Prioritise compatibility profile over core profile
2 parents add2baf + 9129fce commit 42c2a09

18 files changed

Lines changed: 8631 additions & 204 deletions

‎package-lock.json‎

Lines changed: 8329 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/content/docs/current/How To/compatibility_vs_core.mdx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Compatibility vs. Core Profiles
3+
description: An explanation of the difference between the compatibility and core profiles.
4+
sidebar:
5+
label: Compatibility vs. Core Profiles
6+
order: 1
7+
---
8+
9+
## TL;DR
10+
Use the `compatibility` profile.
11+
12+
## The `compatibility` and `core` Profiles
13+
In OpenGL, each new release introduced a new specification for the GLSL language. To indicate which specification is used when compiling the shader, a `#version` directive is provided. Historically, Minecraft used OpenGL 2.0. Newer versions of OpenGL/GLSL dropped support for legacy GLSL features including many predefined attributes starting with `gl_` (for example, `gl_Color`). It is, however, possible to use newer versions of GLSL on an engine using an older version of OpenGL, provided that the hardware supports the version of OpenGL the GLSL version shipped with, through the `compatibility` profile introduced in `#version 150`. By default, the `core` profile is used (disallowing the use of legacy features), however by passing either `compatibility` or `core` after the GLSL version, you can explicitly set which profile is used. In the case of Minecraft for example, it was possible to use `#version 330 compatibility` while still on a version of the game running OpenGL 2.0.
14+
15+
When Minecraft 1.17 released, the game was upgraded to use OpenGL 3.2. This meant that the `compatibility` profile was no longer accessable (note that on most systems apart from MacOS, it can still be used). Since this meant that legacy attributes like `gl_Color` are no longer available, the game provides new attributes such as `vaColor`.
16+
17+
This, however, posed a problem. Existing shaderpacks which used the `compatibility` profile would theoretically no longer function in this new OpenGL version. The solution to this was that shaderpacks would be 'patched' by OptiFine/Iris to use the core profile internally, without any external modifications to the code being required. This means that it is now possible to use either the `core` profile or the `compatibility` profile in an Optifine/Iris shaderpack.
18+
19+
## Which One Should I Use?
20+
21+
There is a common misconception that since the `core` profile is more 'modern', it is preferable over the `compatibility` profile for Minecraft shaderpacks. However, internally, using either will still result in a shaderpack that uses the core profile (on Minecraft 1.17 and newer), and as such, there is no difference in functionality between the two.
22+
23+
However, there are a few reasons why using the `core` profile is *not recommended*. Firstly, the core attributes provided by the game are subject to change. For example, in Minecraft 1.21.2, the attribute `chunkOffset` was renamed to `modelOffset`. However, in Iris, only `chunkOffset` continues to be supported. Thus far, there has been no risk of existing code being broken by changes to the vanilla core profile, however this is not a guarantee.
24+
25+
Secondly, the Iris patcher has been tested much less on core profile code, and there is therefore a higher risk of compilation errors being introduced which can be very difficult to debug when the issue is not actually with your code, but just a quirk of the patcher.
26+
27+
With all of this in mind, it is therefore **recommended that you use the `compatibility` profile**, and *not* the `core` profile.
28+
29+
## Equivalent Attributes/Uniforms
30+
The following is a table showing the mapping between uniforms/attributes from the `compatibility` profile to those in the `core` profile.
31+
32+
| Compatibility | Core | Description |
33+
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
34+
| [`gl_Vertex`](/current/reference/attributes/gl_vertex) | [`vaPosition`](/current/reference/attributes/gl_vertex/#in-vec3-vaposition) + [`chunkOffset`](/current/reference/uniforms/rendering#chunkoffset) | vertex position |
35+
| [`gl_Color`](/current/reference/attributes/gl_color/) | [`vaColor`](/current/reference/attributes/gl_color/#in-vec3-vacolor) | vertex color |
36+
| [`gl_Normal`](/current/reference/attributes/gl_normal) | [`vaNormal`](/current/reference/attributes/gl_normal#in-vec3-vanormal) | vertex normal |
37+
| [`gl_NormalMatrix`](/current/reference/uniforms/matrices#gl_normalmatrix) | [`normalMatrix`](/current/reference/uniforms/matrices#normalmatrix) | normal matrix |
38+
| [`gl_MultiTexCoord0`](/current/reference/attributes/gl_multitexcoord0) | [`vaUV0`](/current/reference/attributes/gl_multitexcoord0#in-vec2-vauv0) | texture uv coordinate |
39+
| [`gl_TextureMatrix[0]`](/current/reference/uniforms/matrices/#gl_texturematrix0) | [`textureMatrix`](/current/reference/uniforms/matrices#gl_texturematrix0) | texture uv matrix |
40+
| [`entityColor`](/current/reference/uniforms/rendering#entitycolor) | [`vaUV1`](/current/reference/attributes/vauv1) (not recommended, even in `core`) | entity overlay |
41+
| [`gl_MultiTexCoord1` / `gl_MultiTexCoord2`](/current/reference/attributes/gl_multitexcoord1) | [`vaUV2`](/current/reference/attributes/gl_multitexcoord1#in-ivec2-vauv2) | lightmap coordinate |
42+
| [`gl_TextureMatrix[1]`](/current/reference/uniforms/matrices/#gl_texturematrix0) | [`TEXTURE_MATRIX_2`](/current/reference/uniforms/matrices/#gl_texturematrix0) (user-defined matrix) | lightmap coordinate matrix |

‎src/content/docs/current/How To/coordinate_spaces.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Coordinate Spaces
33
description: Model space, clip space, and everything in-between
44
sidebar:
55
label: Coordinate Spaces
6-
order: 1
6+
order: 2
77
---
88

99
At the start of a shader program, the vertex position is provided in the form of `gl_Vertex` (or `VAPosition`). This position is in *model space*. By the time it reaches the fragment shader, the position is in *screen space*. Between these two are a number of other coordinate spaces.
@@ -23,7 +23,7 @@ This page is designed to be read in tandem with this cheatsheet, which shows eve
2323
In Iris (and OptiFine), **model space** is whatever coordinate space the vertex position attribute is sent in. The exact coordinate space varies based on the specific geometry, and has the potential to vary across different Minecraft versions. As a result, it is always recommended to treat *model space* like an unknown space and convert to view space with the `gl_ModelViewMatrix`/[`modelViewMatrix`](/current/reference/uniforms/matrices/#modelviewmatrix). **Model space** is also sometimes known as "**local space**".
2424

2525

26-
If using the core profile (and as such using [`vaPosition`](/current/reference/attributes/vaposition) instead of `gl_Vertex`), the *model space* position for terrain should be offset with [`chunkOffset`](/current/reference/uniforms/rendering/#chunkoffset). The conversion sheet assumes this has already been done. Here's an example of what that should look like:
26+
If using the core profile (and as such using [`vaPosition`](/current/reference/attributes/gl_position#in-vec3-vaposition) instead of `gl_Vertex`), the *model space* position for terrain should be offset with [`chunkOffset`](/current/reference/uniforms/rendering/#chunkoffset). The conversion sheet assumes this has already been done. Here's an example of what that should look like:
2727
```glsl
2828
vec3 model_pos = vaPosition + chunkOffset;
2929
```
@@ -49,4 +49,4 @@ It is also worth noting that in third person mode, view bobbing is disabled, and
4949
## Shadow Space
5050
"Shadow Space" can refer to a number of different coordinate spaces, all of which are used for the [shadow pass](/current/reference/programs/shadow/). As such, the "shadow" versions of coordinate spaces are generally equivalent to their normal versions but from the perspective of the shadow camera (the sun/moon). The shadow spaces include **shadow view space**, **shadow clip space**, **shadow NDC space**, and **shadow screen space**.
5151

52-
In the [shadow pass](/current/reference/programs/shadow/), the same base matrices are used ([`modelViewMatrix`](/current/reference/uniforms/matrices/#modelviewmatrix), [`projectionMatrix`](/current/reference/uniforms/matrices/#projectionmatrix), etc), or the `shadow` matrix uniforms (e.g. [`shadowModelView`](/current/reference/uniforms/matrices/#shadowmodelview), [`shadowProjection`](/current/reference/uniforms/matrices/#shadowprojection)) can be used from any program. When sampling the shadow map, positions can be transformed into **player space**, and from there back into *shadow screen space*.
52+
In the [shadow pass](/current/reference/programs/shadow/), the same base matrices are used ([`modelViewMatrix`](/current/reference/uniforms/matrices/#modelviewmatrix), [`projectionMatrix`](/current/reference/uniforms/matrices/#projectionmatrix), etc), or the `shadow` matrix uniforms (e.g. [`shadowModelView`](/current/reference/uniforms/matrices/#shadowmodelview), [`shadowProjection`](/current/reference/uniforms/matrices/#shadowprojection)) can be used from any program. When sampling the shadow map, positions can be transformed into **player space**, and from there back into *shadow screen space*.

‎src/content/docs/current/How To/pbr_standards.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: PBR Standards
33
description: How to interpret PBR data provided by texture packs.
4+
order: 3
45
---
56

67
Texture packs can optionally provide extra data to Iris through the use of normal and specular maps.

src/content/docs/current/Reference/Attributes/vaColor.mdx renamed to src/content/docs/current/Reference/Attributes/gl_Color.mdx

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,31 @@
11
---
2-
title: vaColor
2+
title: gl_Color
33
description: The vertex color attribute.
44
sidebar:
5-
label: vaColor
5+
label: gl_Color
66
order: 2
7-
badge:
8-
text: 1.17+
9-
variant: danger
107
---
118

12-
:::danger
13-
This attribute only works with the `core` profile in Minecraft 1.17 and newer. It is recommended to use the `compatibility` profile with Iris for better support.
14-
:::
15-
16-
### `in vec4 vaColor;`
9+
### `gl_Color`
1710

1811
**Valid Programs**: `gbuffers_*.vsh`, `shadow.vsh`
1912

2013
---
2114

22-
The vertex color attribute, equivalent to `gl_Color` from the `compatibility` profile.
15+
The vertex color attribute.
2316

2417
The color attribute is often used to apply tints to colored blocks such as leaves, grass, water, etc. It also contains the [vanilla ambient occlusion](/current/reference/constants/ambientocclusionlevel/) and, if enabled, the [old lighting](/current/reference/shadersproperties/features/#oldlighting).
2518

26-
Enabling [`separateAo`](/current/reference/shadersproperties/features/#separateao) will move the ambient occlusion from the `rgb` components of `vaColor` to the `a` component, which can be applied later like this:
19+
Enabling [`separateAo`](/current/reference/shadersproperties/features/#separateao) will move the ambient occlusion from the `rgb` components of `gl_Color` to the `a` component, which can be applied later like this:
20+
2721
```glsl
28-
vec3 color = vaColor.rgb * vaColor.a;
29-
```
22+
vec3 color = gl_Color.rgb * gl_Color.a;
23+
```
24+
25+
### `in vec4 vaColor;`
26+
27+
:::danger
28+
This attribute only works with the `core` profile in Minecraft 1.17 and newer. It is recommended to use the `compatibility` profile with Iris for better support. See [this page](/current/how-to/compatibility_vs_core) for more information.
29+
:::
30+
31+
`vaColor` is the equivalent of `gl_Color` for the [core profile](/current/how-to/compatibility_vs_core/).

‎src/content/docs/current/Reference/Attributes/gl_MultiTexCoord0.mdx‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: gl_MultiTexCoord0
3+
description: The vertex UV for the texture atlas.
4+
sidebar:
5+
label: gl_MultiTexCoord0
6+
order: 3
7+
---
8+
9+
### `gl_MultiTexCoord0`
10+
11+
**Valid Programs**: `gbuffers_*.vsh`, `shadow.vsh`, any composite-style pass.
12+
13+
---
14+
15+
The vertex texture coordinate attribute.
16+
17+
Usually the coordinate in `gl_MultiTexCoord0` corresponds directly to the atlas texture coordinate, however some geometry (such as enchantment glint) requires a texture matrix. Therefore, it is always recommended to use [`gl_TextureMatrix[0]`](/current/reference/uniforms/matrices/#gl_texturematrix0).
18+
```glsl
19+
vec2 coord = (gl_TextureMatrix[0] * gl_MultiTexCoord0).xy;
20+
```
21+
22+
### `in vec2 vaUV0;`
23+
:::danger
24+
This attribute only works with the `core` profile in Minecraft 1.17 and newer. It is recommended to use the `compatibility` profile with Iris for better support. See [this page](/current/how-to/compatibility_vs_core) for more information.
25+
:::
26+
27+
It is always recommended to use [`textureMatrix`](/current/reference/uniforms/matrices/#gl_texturematrix0).
28+
29+
```glsl
30+
vec2 coord = (textureMatrix * vec4(vaUV0, 0.0, 1.0)).xy;
31+
```

‎src/content/docs/current/Reference/Attributes/gl_MultiTexCoord1.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: gl_MultiTexCoord1
3+
description: The block and sky lightmap UV coordinates.
4+
sidebar:
5+
label: gl_MultiTexCoord1
6+
order: 3
7+
---
8+
9+
### `gl_MultiTexCoord1`
10+
11+
**Valid Programs**: `gbuffers_*.vsh`, `shadow.vsh`
12+
13+
---
14+
15+
:::note
16+
`gl_MultiTexCoord2` is also valid for the same purposes.
17+
:::
18+
19+
`gl_MultiTexCoord1` stores the block light level in the `x` component, and the sky light level in the `y` component. However, the exact range of the values is indeterminate (though it is currently `0-240`). Therefore, it is recommended to use [`gl_TextureMatrix[1]`](/current/reference/uniforms/matrices/#gl_texturematrix1).
20+
21+
```glsl
22+
vec2 lmcoord = (gl_TextureMatrix[1] * gl_MultiTexCoord1).xy;
23+
```
24+
25+
### `in ivec2 vaUV2;`
26+
27+
:::danger
28+
This attribute only works with the `core` profile in Minecraft 1.17 and newer. It is recommended to use the `compatibility` profile with Iris for better support.
29+
:::
30+
31+
It is recommended to use the following matrix:
32+
33+
```glsl
34+
const mat4 TEXTURE_MATRIX_2 = mat4(vec4(0.00390625, 0.0, 0.0, 0.0), vec4(0.0, 0.00390625, 0.0, 0.0), vec4(0.0, 0.0, 0.00390625, 0.0), vec4(0.03125, 0.03125, 0.03125, 1.0));
35+
36+
vec2 lmcoord = (TEXTURE_MATRIX_2 * vec4(vaUV2, 0.0, 1.0)).xy;
37+
```

‎src/content/docs/current/Reference/Attributes/gl_Normal.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: gl_Normal
3+
description: The normal vector in model space.
4+
sidebar:
5+
label: gl_Normal
6+
order: 2
7+
---
8+
9+
### `gl_Normal`
10+
**Valid Programs**: `gbuffers_*.vsh`, `shadow.vsh`
11+
12+
---
13+
14+
The vertex normal vector attribute.
15+
16+
:::note
17+
The vector is not guaranteed to be normalized.
18+
:::
19+
20+
The normal vector from `gl_Normal` is approximate, and in model space (which varies for different geometry). It can be converted to view space using [`gl_NormalMatrix`](/current/reference/uniforms/matrices/#gl_normalmatrix)
21+
```glsl
22+
vec3 normal = gl_NormalMatrix * normalize(gl_Normal);
23+
```
24+
25+
### `in vec3 vaNormal;`
26+
:::danger
27+
This attribute only works with the `core` profile in Minecraft 1.17 and newer. It is recommended to use the `compatibility` profile with Iris for better support. See [this page](/current/how-to/compatibility_vs_core) for more information.
28+
:::
29+
30+
Can be converted to view space using [`normalMatrix`](/current/reference/uniforms/matrices/#gl_normalmatrix)
31+
```glsl
32+
vec3 normal = normalMatrix * normalize(vaNormal);
33+
```

‎src/content/docs/current/Reference/Attributes/gl_Vertex.mdx‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: gl_Vertex
3+
description: The vertex position in model space.
4+
sidebar:
5+
label: gl_Vertex
6+
order: 2
7+
---
8+
9+
### `gl_Vertex`
10+
11+
**Valid Programs**: `*.vsh`
12+
13+
---
14+
15+
The vertex position attribute in model space (which varies for different geometry). It can be converted to view space using [`gl_ModelViewMatrix`](/current/reference/uniforms/matrices/#gl_modelviewmatrix)
16+
17+
```glsl
18+
vec3 model_pos = gl_Vertex.xyz;
19+
vec4 view_pos = gl_ModelViewMatrix * vec4(model_pos, 1.0);
20+
vec4 clip_pos = gl_ProjectionMatrix * view_pos;
21+
22+
gl_Position = clip_pos;
23+
```
24+
25+
### `in vec3 vaPosition;`
26+
27+
:::danger
28+
This attribute only works with the `core` profile in Minecraft 1.17 and newer. It is recommended to use the `compatibility` profile with Iris for better support. See [this page](/current/how-to/compatibility_vs_core) for more information.
29+
:::
30+
31+
For terrain this is relative to the chunk and you must add [`chunkOffset`](/current/reference/uniforms/rendering/#chunkoffset) as shown below. For all other geometry, `vaPosition` directly stores the model space position. It can be converted to view space using [`modelViewMatrix`](/current/reference/uniforms/matrices/#gl_modelviewmatrix)
32+
33+
```glsl
34+
vec3 model_pos = vaPosition + chunkOffset;
35+
vec4 view_pos = modelViewMatrix * vec4(model_pos, 1.0);
36+
vec4 clip_pos = projectionMatrix * view_pos;
37+
38+
gl_Position = clip_pos;
39+
```

‎src/content/docs/current/Reference/Attributes/overview.mdx‎

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,3 @@ sidebar:
77
---
88

99
**Attributes** are per-vertex data available *only* in the vertex stage. These values encode most of the information that is specific to each vertex, compared to [uniforms](/current/reference/uniforms/overview/) which are the same across all vertices/fragments of a shader. Attribute data can be passed to the fragment stage with a `varying`, or stored to a buffer and read for any other shaders.
10-
11-
12-
### Profile-specific attributes
13-
The GLSL `compatibility` profile provides several built in attributes. Iris/OptiFine provide several attributes/uniforms to replace these when using the `core` profile. These "core profile" attributes are only available in Minecraft 1.17 and later. The following table shows these attributes:
14-
15-
| Compatibility | Core | Description |
16-
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
17-
| `gl_Vertex` | [`vaPosition`](/current/reference/attributes/vaposition/) + [`chunkOffset`](/current/reference/uniforms/rendering/#chunkoffset) | vertex position |
18-
| `gl_Color` | [`vaColor`](/current/reference/attributes/vacolor/) | vertex color |
19-
| `gl_Normal` | [`vaNormal`](/current/reference/attributes/vanormal/) | vertex normal |
20-
| `gl_NormalMatrix` | [`normalMatrix`](/current/reference/uniforms/matrices/#normalmatrix) | normal matrix |
21-
| `gl_MultiTexCoord0` | [`vaUV0`](/current/reference/attributes/vauv0/) | texture uv coordinate |
22-
| `gl_TextureMatrix[0]` | [`textureMatrix`](/current/reference/uniforms/matrices/#texturematrix) | texture uv matrix |
23-
| [`entityColor`](/current/reference/uniforms/rendering/#entitycolor) | [`vaUV1`](/current/reference/attributes/vauv1/) (not recommended, even in `core`) | entity overlay |
24-
| `gl_MultiTexCoord1` / `gl_MultiTexCoord2` | [`vaUV2`](/current/reference/attributes/vauv2/) | lightmap coordinate |
25-
| `gl_TextureMatrix[1]` | [`TEXTURE_MATRIX_2`](/current/reference/attributes/vauv2/) (hardcoded matrix) | lightmap coordinate matrix |

0 commit comments

Comments
 (0)