Luminance

So... what's Luminance? Luminance is a library mod that helps with shader rendering. It helps mod developers setup shader rendering so they can focus on the shaders themselves! Luminance also adds Dynamic Uniforms, which allow developers to pass information to their shaders - we also include some default ones!

Are you a user that wants to see Luminance in action?
Try out Souper Secret Settings by Nettakrim, or Perspective by dannytaylor!

Luminance Documentation hasn't been written yet (it's on the top of our todo list!), however both Souper Secret Settings and Perspective are both open source so you can always see how we use it!
You can also check out our Resourcepack Guide which explains how to create a luminance shader resource pack.

Luminance Shader Resource Reloader Format

To make things simple, we've added a new resource to resource packs, which is located at assets/<namespace>/luminance/<id>.json.

{  
  "post_effect": "namespace:id", // defaults to `modid:shaderid` of the json file if not specified, this specifies the location of the post effect json.  
  "enabled": true, // defaults to true, specifies whether the shader can be used.  
  "disable_ui_rendertype": true, // defaults to false, specifies whether the shader can be rendered using the `UI` render type.  
  "registries": [ // If not provided, the shader will be registered to "luminance:main", if you do provide this, it will only be registered to the specified registries.  
    "luminance:main" // This is the default registry, most mods using Luminance should be using this.  
  ]
  "custom": {  
    "namespace": {} // defaults to new JsonObject(), can be obtained in the `ShaderRegistryEntry`.  
  }  
}  

Dynamic Uniforms

We include some default dynamic uniforms that any mod using Luminance can use in their shaders!

Custom Mod Menu Icon

Luminance adds a way to change the icon used for your mod. Want a custom icon that only shows on October 31st? You can do that: CompatHelper.addOverrideModMenuIcon(new Couple<>("modid", "halloween"), () -> "assets/modid/icons/halloween.png", () -> LocalDate.now().getMonth() == Month.October && LocalDate.now().getDayOfMonth() == 31);
You can also add a Luminance badge to your mod using:
addLuminanceModMenuBadge("modid");

Iris Shaders Compatibility

You can render both Luminance and Iris shaders at the same time! You can also check if Iris has shaders enabled by using CompatHelper.isIrisShadersEnabled()

Licenced under LGPL-3.0-or-later

Developer's note
We're working on a way for one jar for both quilt, and fabric (and eventually neoforge - that's going to take some time though!). If you have any thoughts, please share them here!

If no bugs are found in this rc, we will fully release Luminance 1.0.

• Fixed Hand Depth. (Nettakrim)
• Added luminance:aa antialias shader. (dannytaylor, Nettakrim)
• Updated variable, and function names to be more relevant for the context of shader rendering. (dannytaylor)
  • GAME -> UI, SCREEN_BACKGROUND -> UI_BACKGROUND, afterGameRender -> afterUiRender, afterScreenBackgroundRender -> afterUiBackgroundRender, afterHandRender -> afterVanillaPostEffectRender, afterWeatherRender -> afterFabulousRender
• Updated luminance json dataloader. (dannytaylor)
  • "disable_game_rendertype" has been renamed to "disable_ui_rendertype".
    • If "disable_ui_rendertype" cannot be found, it will check for "disable_game_rendertype", and "disable_screen_mode", before defaulting to false.
• _smooth uniforms now lerp with a nonlinear deltatime factor, such that they will be the same speed regardless of framerate. (Nettakrim)
• changed default value for luminance:post/scanlines Amount uniform from 800 to 2 (it looks nearly identical but is in the range where it directly affects the size of the lines, instead of only working because of moire with pixels). (Nettakrim)
• Added luminance_cam and luminance_cam_fract uniforms. (Nettakrim)
• Added luminance_clipping uniform that returns the near and far clipping planes, this allows linearizeDepth to be actually correct. (Nettakrim)
• Updated the alpha slider used in the config screen to have it's own class. (it's functionally the same). (Nettakrim)

Developers note
There is currently a bug with our development environment that causes mod-loader specific classes to sometimes not be loaded, however this doesn't effect the final build.
After releasing v1.0, I'll work on a fix for this, which will also allow for a merged jar for both quilt and fabric - and eventually neoforge.

If no bugs are found in this rc, we will fully release Luminance 1.0.

• Fixed environment issue relating to servers. (dannytaylor)
• Updated Shader Translations to fallback to an empty string. (dannytaylor)
• Ported soup_range config to be a default luminance feature range. (Nettakrim)
• target sizes can now be set based on simple linear equations of the screen size and width. (Nettakrim)
• vanilla spectator no longer disabled when on ALL mode. (Nettakrim)
• Shaders.get() no longer uses the index to check for a shader entry. (Nettakrim)
• Shaders.guessPostShader() now returns an Optional<ShaderRegistryEntry>. (Nettakrim)
• Shaders.guessPostShader() guesses namespace even if namespace is already given, prioritizing the existing one. (Nettakrim)
• backported clear_color from 25w16a ("persistent" had already been implemented :P). (Nettakrim)
• fixed "enabled": false not working properly. (Nettakrim)
• currentAir and currentHurtTime now use callable ranges. (Nettakrim)
• Fixed _smooth and _delta dynamic uniforms. (Nettakrim)
• Mod Initializers have been removed, the Quilt version now checks if qsl_base is not present and implements init, client_init, and server_init. (dannytaylor)

• Updated to 1.21.4
• Updated Included Shaders
• Updated Dynamic Uniforms
• Added Uniform Config
• Added PANORAMA and SCREEN_BACKGROUND Render Types
• Native Fabric and Quilt versions
• Added Spectator Shader Manager

For the latest information about how to use luminance, check out the guide.

You won't need the common jar unless you're making a multi-loader mod.

Developers Note: This version should work for 1.21 and 1.21.1. 1.21.2 snapshots contain alot of shader related changes, and will break shaders made for 1.21.1 and earlier. The next alpha will update to 1.21.2 and will change where shaders are registered, and will contain a change to the registry format.

Changelog

Features

• Added Message Overlay.
• Updated Events.
  • OnShaderDataReset
    • Runnables registered here will run when the shader registry is reset.
      • It will most commonly happen when reloading resources.
  • OnShaderDataRegistered
    • Runnables.ShaderData registered here will run when a shader is registered in the dataloader.
  • OnShaderDataRemoved
    • Runnables.ShaderData registered here will run when a shader is removed from the dataloader.
      • It will most commonly happen if a resource pack sets the shader's enabled variable to false, after the shader has already been registered.
  • AfterShaderDataRegistered
    • Runnables registered here will run after the shader dataloader has finished loading.
  • BeforeWorldRender
    • Runnables registered here will run before the world is rendered.
  • AfterWorldBorder
    • Runnables registered here will run after the world border is rendered.
  • AfterWorldRender
    • Runnables registered here will run after the world is rendered.
  • AfterGameRender
    • Runnables registered here will run after everything is rendered.
  • BeforeShaderRender
    • Runnables registered here will run before a shader is rendered.
  • AfterShaderRender
    • Runnables registered here will run after a shader is rendered.
  • ShaderUniform
    • You can now modify/remove uniforms.
      • If you want to update a uniform, make the callable call a variable.
      • You should only modify the uniform if you are changing what the callable calls.
  • ShaderRender
    • Shaders registered here will be rendered by Luminance.
      • When registering a shader, you will include a new Couple<>(modId, shaders) id, this allows mods to have multiple shaders rendered and allows you to modify them.
      • When registering a shader, you will also include a list of shaders.
        • new Couple<String, Shader>("id", new Shader(id, renderType))
          • The shader is stored in a couple and consists of a String and the shader itself.
            • The string can be anything, but there can only be one shader with that string.
              • It can be used to locate a specific shader to either modify or remove.
            • The shader consists of an Identifier and a Shader.RenderType.
              • The Identifier should lead to your /shaders/post/x.json file.
              • The RenderType can be set to Shader.RenderType.GAME or Shader.RenderType.WORLD.
                • GAME renders the shader over everything including menus.
                  • Shaders with disable_game_rendertype set to true will render in WORLD instead.
                • WORLD renders only in-game behind your GUI.
• Added Shader Namespace Identifier Fix.
• Added Shader Texture Namespace Identifier Fix.
• Added Shader Dataloader.
  • Shaders registered here will be added to ShaderDataloader.registry.
  • The layout is based on Perspective's shader dataloader, but shaders made with this layout will NOT get registered by Perspective (yet, it'll be updated to use this layout instead in a future update!)
  • Dataloader Example
    • This example will register the perspective:silhouette shader, will always render in the WORLD rendertype, and can be translated.
    • The custom field can contain objects that can be read by third party mods - e.g. perspective.

{
  "namespace": "perspective",
  "name": "silhouette",
  "enabled": true,
  "translatable": true,
  "disable_game_rendertype": true,
  "custom": {
    "perspective": {
      "entity_links": [
        "entity.minecraft.warden"
      ]
    },
    "souper_secret_settings": {
      "disable_soup": false,
      "entity_links": [
        "entity.minecraft.warden"
      ]
    }
  }
}

• If you're updating a perspective shader, you will need to update the following:
  • shader has been renamed to name.
  • disable_screen_mode has been renamed to disable_game_rendertype.
  • entity_links is now contained within the perspective custom object.
• Added ModMenu Icon Override.
  • You can override the icon ModMenu displays for your mod by using the following code on mod initialization:
    • CompatHelper.addOverrideModMenuIcon(new Couple<>("modId", "type"), "assets/modId/alt_icon.png", () -> {return true;});
• Added ModMenu Luminance Badge.
  • You can add the Luminance ModMenu Badge to your mod by using the following code on mod initialization.
    • CompatHelperaddLuminanceModMenuBadge("modId");

Config Version 2

• Added show_alpha_level_overlay boolean config option.
  • When set to true, changing the alpha level using the keybinding will display the percentage on screen.

Development Build

Please help us improve by submitting bug reports if you encounter any issues.

Want to support my work?

If you'd like to donate, visit BuyMeACoffee.
Your support is appreciated, please be aware that donations are non-refundable.

This version only changes what is needed for Minecraft 1.21.

Changelog

• Ported 1.0.0-alpha.3+1.20.5/6 to Minecraft 1.21.

Alpha 4 Development

1.0.0-alpha.4 will add alot of shader rendering stuff, and will be released within the next few weeks.

Development Build

Please help us improve by submitting bug reports if you encounter any issues.

Want to support my work?

If you'd like to donate, visit BuyMeACoffee.
Your support is appreciated, please be aware that donations are non-refundable.

Luminance 1.0.0-alpha.3 for 1.20.5/6

Changelog

• You can now modify and remove dynamic shader uniforms callables, and BeforeRender runnables.
  • Note, this version will break compatibility with mods that used BeforeRender runnables, as it now requires an id.

If you want to update a dynamic uniform, you don't need to modify it. When registering the uniform, just make the callable return a variable that you can update in your mod!

Development Build

Please help us improve by submitting bug reports if you encounter any issues.

Want to support my work?

If you'd like to donate, visit BuyMeACoffee.
Your support is appreciated, please be aware that donations are non-refundable.

Luminance 1.0.0-alpha.2 for 1.20.5-rc3

Small update to check if Iris is enabled.

Changelog

Features

• Added CompatHelper.isIrisShadersEnabled() boolean check.
  • Returns true if Iris is both installed and a shader pack is enabled.

Development Build

Please help us improve by submitting bug reports if you encounter any issues.

Want to support my work?

If you'd like to donate, visit BuyMeACoffee.
Your support is appreciated, please be aware that donations are non-refundable.

Luminance 1.0.0-alpha.1 for 1.20.5-rc2

Changelog

Config Version 1

• Added integer config option alpha_level.
  • This value is clamped between 0 and 100.

Features

• Added Dynamic Shader Uniforms.
  • You can add custom dynamic shader uniforms using:
    • ShaderRenderEvents.ShaderUniform.registerFloat("modid", "example", Uniforms::getExample);
    • ShaderRenderEvents.ShaderUniform.registerFloats("modid", "example", Uniforms::getExample);
    • ShaderRenderEvents.ShaderUniform.registerVector3f("modid", "example", Uniforms::getExample);
    • In this example, your dynamic uniform name will be modid_example.
  • Luminance also comes with some already registered.
    • lu_viewDistance
    • lu_fov
    • lu_fps
    • lu_time
    • lu_eyePosition
    • lu_position
    • lu_pitch
    • lu_yaw
    • lu_currentHealth
    • lu_maxHealth
    • lu_currentAbsorption
    • lu_maxAbsorption
    • lu_currentHurtTime
    • lu_maxHurtTime
    • lu_currentAir
    • lu_maxAir
    • lu_isSprinting
    • lu_isSwimming
    • lu_isSneaking
    • lu_isCrawling
    • lu_isInvisible
    • lu_isWithered
    • lu_isPoisoned
    • lu_isBurning
    • lu_isOnGround
    • lu_isOnLadder
    • lu_isRiding
    • lu_hasPassengers
    • lu_biomeTemperature
    • lu_alpha
    • lu_perspective
    • lu_viewDistanceSmooth
    • lu_fovSmooth
    • lu_timeSmooth
    • lu_eyePositionSmooth
    • lu_positionSmooth
    • lu_pitchSmooth
    • lu_yawSmooth
    • lu_currentHealthSmooth
    • lu_maxHealthSmooth
    • lu_currentAbsorptionSmooth
    • lu_maxAbsorptionSmooth
    • lu_currentHurtTimeSmooth
    • lu_maxHurtTimeSmooth
    • lu_currentAirSmooth
    • lu_maxAirSmooth
    • lu_isSprintingSmooth
    • lu_isSwimmingSmooth
    • lu_isSneakingSmooth
    • lu_isCrawlingSmooth
    • lu_isInvisibleSmooth
    • lu_isWitheredSmooth
    • lu_isPoisonedSmooth
    • lu_isBurningSmooth
    • lu_isOnGroundSmooth
    • lu_isOnLadderSmooth
    • lu_isRidingSmooth
    • lu_hasPassengersSmooth
    • lu_biomeTemperatureSmooth
    • lu_alphaSmooth
  • This list of included dynamic shader uniforms will change over time, more will be added in future updates.
    • If you are a shader developer and need something custom, or just have a suggestion for a new dynamic shader uniform, add an issue to the Issues page with what you need, and it'll get added.

Resource Packs

Perspective: Default

• Added Super Secret Settings Resource Pack.
  • This resource pack contains shaders that have been used in previous minecraft versions.
  • Requires Perspective or Souper Secret Settings.

Development Build

Please help us improve by submitting bug reports if you encounter any issues.

Want to support my work?

If you'd like to donate, visit BuyMeACoffee.
Your support is appreciated, please be aware that donations are non-refundable.