ppy/osu-framework 2023.314.0

on GitHub

Breaking Changes

The OpenGL Core profile is now used

Shaders now follow "Vulkan GLSL", which is mostly documented in the spec: GL_KHR_vulkan_glsl. The primary differences are documented below:

Vertex shader members

attribute lowp int In_Value;
varying lowp int Out_Value;

layout(location = 0) in lowp int InValue;
layout(location = 0) out lowp int OutValue;

The location increases for each additional member in the respective in/out lists.

Fragment shader members

varying lowp int In_Value;

layout(location = 0) in lowp int InValue;

The location increases for each additional member, and must match the location of the respective member in the vertex shader.

Fragment shader outputs

Fragment shaders are required to define an output variable.

void main(void)
{
    gl_FragColor = vec4(0.0);
}

layout(location = 0) out vec4 colour;

void main(void)
{
    colour = vec4(0.0);
}

Uniform members

Free-floating "global" uniforms are not supported. They must be placed in "uniform blocks".

uniform lowp int Uniform_Value;

layout(std140, set = 0, binding = 0) uniform MyUniforms
{
    lowp int Uniform_Value;
};

Notes:

• std140 should always be used.
• The set increases for each unique uniform block.
• binding is a special required value which indicates where in the program the block should be bound. osu!framework manages this for you and should be 0 for uniform blocks.
• Both shader stages can use the same uniform block from the same set, provided that the physical layout matches.

Furthermore, this means that uniform blocks have become a first-class citizen in osu!framework. The code to make use of the above looks like this:

class MyDrawNode : DrawNode
{
    private IUniformBuffer<MyBufferData>? bufferData;

    public override void Draw(IRenderer renderer)
    {
        base.Draw(renderer);

        // Create the uniform buffer.
        bufferData ??= renderer.CreateUniformBuffer<MyBufferData>();

        // Update the uniform buffer.
        bufferData.Data = bufferData.Data with
        {
            UniformValue = 5
        };

        // Bind the buffer to the shader.
        shader.BindUniformBuffer("MyUniforms", bufferData);

        shader.Bind();
        // Draw...
    }

    protected override void Dispose(bool isDisposing)
    {
        base.Dispose(isDisposing);

        // Ensure that the buffer is disposed.
        bufferData?.Dispose();
    }
}

// Pack = 1 is required.
[StructLayout(LayoutKind.Sequential, Pack = 1)]
// Record structs automatically implement IEquatable<>
public record struct MyBufferData
{
    // Use types provided in the osu.Framework.Graphics.Shaders.Types namespace.
    public UniformInt UniformValue;

    // The struct must be a multiple of 16 bytes.
    private readonly UniformPadding12 pad2;
}

Runtime validation is present to notify of incorrect alignment/packing.

Uniform textures/samplers

The combined sampler of GLSL is not supported.

uniform lowp sampler2D Sampler;

layout(set = 0, binding = 0) uniform lowp texture2D Texture;
layout(set = 0, binding = 1) uniform lowp sampler Sampler;

Notes:

• std140 cannot be applied here unlike for uniform blocks.
• The set increases along with all other uniform blocks/textures.
• The texture and sampler are bound to different points. The texture being bound to 0 and sampler to 1 will be standard for osu!framework going forward.

Sampling textures

vec4 col = texture2D(my_Sampler, ...);

vec4 col = texture(sampler2D(my_Texture, my_Sampler), ...);

What's Changed

• Add BindableColour4 by @Poyo-SSB in #5660
• Fix external links not working on Android by @Joehuu in #5666
• Allow displays with no display modes by @Susko3 in #5665
• Add simple Quad.Contains tests by @peppy in #5668
• Fix Quad.Contains sometimes failing due to floating point precision issues by @bdach in #5670
• Add OpenGL Core renderer and use as default by @smoogipoo in #5655
• Update github actions to latest versions by @peppy in #5673
• Remove xmldoc references to private methods by @peppy in #5672
• Implement Veldrid renderer by @smoogipoo in #5661
• Show current renderer and surface choice in frame display by @peppy in #5662
• Fix Veldrid + OpenGL not initialising on macOS by @smoogipoo in #5676
• Fix UBOs not being initialised when data is default by @smoogipoo in #5675

New Contributors

• @Poyo-SSB made their first contribution in #5660

Full Changelog: 2023.228.0...2023.314.0