Package org.dark.shaders.util

Class ShaderLib

java.lang.Object
org.dark.shaders.util.ShaderLib
public final class ShaderLib extends Object
This class performs a variety of functions designed to assist in shader-writing.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    ShaderLib.QuickHandler
     

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final boolean
    DEBUG_CALLBACK_NO_VANILLA
     
    static final Comparator<com.fs.starfarer.api.combat.ShipAPI>
    SHIP_DRAW_ORDER
     
    static final boolean
    VALIDATE_EVERY_FRAME
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    ShaderLib()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    addMapObject(MapObjectAPI mapObject)
    Adds an arbitrary material/normal/surface-mapped object to the rendering list.
    static void
    addShaderAPI(ShaderAPI shader)
    Adds the given instance of ShaderAPI to the rendering queue.
    static boolean
    areBuffersAllowed()
    Do not use FBOs if this returns false! Otherwise the game will crash!
    static boolean
    areShadersAllowed()
    Do not use shader code if this returns false! Otherwise the game will crash!
    static void
    beginDraw(int shader)
    This function is meant to be used at the start of the shader's rendering stage.
    static float
    clampAngle(float degrees)
    Clamps an angle to the range -180 to 180 degrees.
    static void
    copyScreen(int texture, int textureUnit)
    This function copies the current screen to the given texture and binds that texture to the given texture unit.
    static void
    drawScreenQuad(float scale)
    This function draws a quad formatted to fit the whole screen, with texture coordinates mapped such that the entire screen texture (which is usually a size like 2048x2048) is represented by the range [0,0] to [1,1].
    static void
    exitDraw()
    This function is meant to be used at the end of the shader's rendering stage.
    static void
    exitDraw(int boundTex, int activeTex)
    This function is meant to be used at the end of the shader's rendering stage.
    static double
    fastCos(double radians)
    Get the cosine of an angle.
    static double
    fastSin(double radians)
    Get the sine of an angle.
    static int
    getAuxiliaryBufferId()
    Returns the framebuffer object ID of the auxiliary buffer.
    static int
    getAuxiliaryBufferTexture()
    Returns the texture ID of the texture pointed to by the auxiliary buffer.
    static int
    getForegroundTexture(com.fs.starfarer.api.combat.ViewportAPI viewport)
    Returns the texture ID of the framebuffer texture containing every foreground object.
    static int
    getInternalHeight()
    Gets the height of ShaderLib's screen texture.
    static int
    getInternalWidth()
    Gets the width of ShaderLib's screen texture.
    static List<MapObjectAPI>
    getMapObjects()
    Returns the rendering list of mapped objects.
    static String
    getProgramLogInfo(int obj)
     
    static int
    getScreenTexture()
    Returns the texture ID of the texture allocated for the purpose of storing the current rendered screen.
    static ShaderAPI
    getShaderAPI(Class<? extends ShaderAPI> shaderAPI)
    Returns the loaded instance of the given class that implements ShaderAPI.
    static List<ShaderAPI>
    getShaderAPIsCopy()
    The returned list is read-only and sorted in render order.
    static String
    getShaderLogInfo(int obj)
     
    static TextureEntry
    getShipTexture(com.fs.starfarer.api.combat.ShipAPI ship, TextureData.TextureDataType type)
    Retrieves the most appropriate TextureEntry corresponding to the given ship and texture type.
    static float
    getSquareTransform()
    Gets a transformation scalar for the x axis to pass to the shader to grant it a proper aspect ratio.
    static org.lwjgl.util.vector.Vector2f
    getTextureDataNormalization(float minValue, float maxValue)
    Gets a scalar (x) and offset (y) to transform any range of floats to a texture's standard [0,1] clamp.
    static float
    getVisibleU()
    Gets the fraction of the U component of ShaderLib's screen texture that is visible on screen.
    static float
    getVisibleV()
    Gets the fraction of the V component of ShaderLib's screen texture that is visible on screen.
    static TextureEntry
    getWeaponTexture(com.fs.starfarer.api.combat.WeaponAPI weapon, TextureData.TextureDataType texType, TextureData.ObjectType objType, int frame)
    Retrieves the most appropriate TextureEntry corresponding to the given weapon, texture, and object type.
    static void
    handleMessage(int source, int type, int id, int severity, String message, boolean includeTrace, boolean suppressIdentical, String title)
    Debug function for printing GL error codes.
    static void
    init()
    Starts up ShaderLib; many mods may call this method but only the first will actually do anything.
    static boolean
    isAACompatMode()
    Returns the state of the antialiasing compatibility mode option.
    static boolean
    isForegroundEmpty(com.fs.starfarer.api.combat.ViewportAPI viewport)
    Returns true if there is no combat engine.
    static boolean
    isOnScreen(org.lwjgl.util.vector.Vector2f worldCoords, float radius)
    Checks if a point, bounded by a certain radius, is on screen.
    static boolean
    isOnScreen(org.lwjgl.util.vector.Vector2f worldCoords1, org.lwjgl.util.vector.Vector2f worldCoords2, float radius)
    Checks if a line, bounded by a certain radius, is on screen.
    static int
    loadShader(String vert, String frag)
    Compiles the given shader.
    static int
    makeFramebuffer(int attachment, int texture, int texWidth, int texHeight, int mipLevel)
    Creates a framebuffer object for the given texture.
    static void
    overrideShipTexture(com.fs.starfarer.api.combat.ShipAPI ship, String id)
    Overrides a ship's ID for the purposes of determining which TextureEntry to use within shaders (such as lighting).
    static void
    overrideWeaponTexture(com.fs.starfarer.api.combat.WeaponAPI weapon, String id)
    Overrides a weapon's ID for the purposes of determining which TextureEntry to use within shaders (such as lighting).
    static void
    removeMapObject(MapObjectAPI mapObject)
    Removes a mapped object from the rendering list.
    static void
    screenDraw(int texture, int textureUnit)
    This function combines the functionalities of copyScreen and drawScreenQuad.
    static org.lwjgl.util.vector.Vector2f
    transformScreenToUV(org.lwjgl.util.vector.Vector2f screenCoords)
    Transforms relative screen coordinates to UV texture coordinates.
    static org.lwjgl.util.vector.Vector2f
    transformWorldToScreen(org.lwjgl.util.vector.Vector2f worldCoords)
    Transforms absolute world coordinates to relative screen coordinates, unscaled.
    static float
    unitsToUV(float units)
    Transforms a distance given in absolute world space units to UV distance.
    static boolean
    useBufferARB()
    Whether to use the ARB_framebuffer_object implementation of FBOs.
    static boolean
    useBufferCore()
    Whether to use the core OpenGL 3.0 implementation of FBOs.
    static boolean
    useBufferEXT()
    Whether to use the EXT_framebuffer_object implementation of FBOs.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • SHIP_DRAW_ORDER

      public static final Comparator<com.fs.starfarer.api.combat.ShipAPI> SHIP_DRAW_ORDER

    • VALIDATE_EVERY_FRAME

      public static final boolean VALIDATE_EVERY_FRAME
      See Also:

    • DEBUG_CALLBACK_NO_VANILLA

      public static final boolean DEBUG_CALLBACK_NO_VANILLA
      See Also:

  • Constructor Details

    • ShaderLib

      public ShaderLib()

  • Method Details

    • addShaderAPI

      public static void addShaderAPI(ShaderAPI shader)
      Adds the given instance of ShaderAPI to the rendering queue. Duplicates of the same shader or same type of shader are invalid. The shader will be added even if ShaderLib is not enabled.

      Parameters:
      shader - The shader to add.

    • areBuffersAllowed

      public static boolean areBuffersAllowed()
      Do not use FBOs if this returns false! Otherwise the game will crash!

      Returns:
      Whether the user can use framebuffer objects.

    • areShadersAllowed

      public static boolean areShadersAllowed()
      Do not use shader code if this returns false! Otherwise the game will crash!

      Returns:
      Whether the user can use shaders (has OpenGL 2.0 support).

    • isAACompatMode

      public static boolean isAACompatMode()
      Returns the state of the antialiasing compatibility mode option.

      Returns:
      The current "aaCompatMode" setting.

      Since:
      v1.5.1

    • beginDraw

      public static void beginDraw(int shader)
      This function is meant to be used at the start of the shader's rendering stage. This sets also sets glOrtho to a screen-space value.

      This function pushes GL_PROJECTION, GL_TEXTURE, and GL_MODELVIEW (in that order) onto the stack, and also pushes GL_ALL_ATTRIB_BITS to the stack. exitDraw() can be used to undo the changes caused by this function; if you do not do so, errors may occur.

      Parameters:
      shader - The shader program ID to bind the renderer to.

    • clampAngle

      public static float clampAngle(float degrees)
      Clamps an angle to the range -180 to 180 degrees.

      Parameters:
      degrees - The angle.

      Returns:
      An angle, clamped to -180 to 180 degrees.

    • copyScreen

      public static void copyScreen(int texture, int textureUnit)
      This function copies the current screen to the given texture and binds that texture to the given texture unit. This function is meant to be used when the uniform parameters have been bound during the shader's rendering stage.

      Parameters:
      texture - The texture to copy to.
      textureUnit - The texture unit to bind the given texture to.

    • drawScreenQuad

      public static void drawScreenQuad(float scale)
      This function draws a quad formatted to fit the whole screen, with texture coordinates mapped such that the entire screen texture (which is usually a size like 2048x2048) is represented by the range [0,0] to [1,1]. Not intended for world coordinates.

      Parameters:
      scale - How much to scale the quad by (usually for subsampling purposes).

      Since:
      Alpha 1.2

    • exitDraw

      public static void exitDraw()
      This function is meant to be used at the end of the shader's rendering stage.

      This function pops GL_MODELVIEW, GL_TEXTURE, and GL_PROJECTION (in that order) from the stack, and also pops state variables from the stack. See beginDraw(int shader).

    • exitDraw

      public static void exitDraw(int boundTex, int activeTex)
      This function is meant to be used at the end of the shader's rendering stage. Special function to call glActiveTexture and glBindTexture with specific IDs rather than relying on automatic behavior.

      Parameters:
      boundTex - Texture to bind
      activeTex - Texture to make active

    • fastCos

      public static double fastCos(double radians)
      Get the cosine of an angle. From LazyLib's FastTrig library, designed by JeffK.

      Parameters:
      radians - The angle.

      Returns:
      The cosine of the angle.

    • fastSin

      public static double fastSin(double radians)
      Get the sine of an angle. From LazyLib's FastTrig library, designed by JeffK.

      Parameters:
      radians - The angle.

      Returns:
      The sine of the angle.

    • getAuxiliaryBufferId

      public static int getAuxiliaryBufferId()
      Returns the framebuffer object ID of the auxiliary buffer. The auxiliary buffer may be used for any drawing you might need as input for another shader. The auxiliary buffer is not preserved between frames.

      The auxiliary buffer texture is a 32-bit or 64-bit RGBA texture with the smallest power-of-two size that fits the visible screen. It has mipmaps and a floating-point internal type.

      Returns:
      The framebuffer object ID of the auxiliary buffer. Returns 0 if framebuffer objects are not supported.

      Since:
      Alpha v1.6

    • getAuxiliaryBufferTexture

      public static int getAuxiliaryBufferTexture()
      Returns the texture ID of the texture pointed to by the auxiliary buffer. The auxiliary buffer may be used for any drawing you might need as input for another shader. The auxiliary buffer is not preserved between frames.

      The auxiliary buffer texture is a 32-bit or 64-bit RGBA texture with the smallest power-of-two size that fits the visible screen. It has mipmaps and a floating-point internal type.

      Returns:
      The texture ID of the texture pointed to by the auxiliary buffer. Returns 0 if framebuffer objects are not supported.

      Since:
      Alpha v1.6

    • getForegroundTexture

      public static int getForegroundTexture(com.fs.starfarer.api.combat.ViewportAPI viewport)
      Returns the texture ID of the framebuffer texture containing every foreground object. Useful for object-space shaders. Returns 0 if there is no combat engine. Do not use this if the user does not have framebuffer object support!

      Warning: This function may reset your framebuffer binding to 0! You should save your framebuffer parameters (if any) prior to calling this function! Note that this function uses any Material maps associated with those foreground objects.

      Parameters:
      viewport - The viewport in use by the renderer.

      Returns:
      The texture ID of the framebuffer texture containing every foreground object. Includes any Material maps associated with those foreground objects.

    • getInternalHeight

      public static int getInternalHeight()
      Gets the height of ShaderLib's screen texture.

      Returns:
      The height of ShaderLib's screen texture.

    • getInternalWidth

      public static int getInternalWidth()
      Gets the width of ShaderLib's screen texture.

      Returns:
      The width of ShaderLib's screen texture.

    • getProgramLogInfo

      public static String getProgramLogInfo(int obj)

    • getScreenTexture

      public static int getScreenTexture()
      Returns the texture ID of the texture allocated for the purpose of storing the current rendered screen.

      Returns:
      The texture ID of the texture allocated for the purpose of storing the currently-rendered screen.

      Since:
      Alpha v1.03

    • getShaderAPI

      public static ShaderAPI getShaderAPI(Class<? extends ShaderAPI> shaderAPI)
      Returns the loaded instance of the given class that implements ShaderAPI. Returns null if there is no instance of the given shader.

      Parameters:
      shaderAPI - The class to search for. Must implement ShaderAPI.

      Returns:
      The instance of the given shader. Returns null if there is no instance of the given shader.

      Since:
      Alpha 1.02

    • getShaderAPIsCopy

      public static List<ShaderAPI> getShaderAPIsCopy()
      The returned list is read-only and sorted in render order.

      Returns:
      A read-only copy of the loaded ShaderAPI objects.

    • getShaderLogInfo

      public static String getShaderLogInfo(int obj)

    • getSquareTransform

      public static float getSquareTransform()
      Gets a transformation scalar for the x axis to pass to the shader to grant it a proper aspect ratio.

      Returns:
      The transformation scalar for the x axis to pass to a shader to grant it a proper aspect ratio.

    • getTextureDataNormalization

      public static org.lwjgl.util.vector.Vector2f getTextureDataNormalization(float minValue, float maxValue)
      Gets a scalar (x) and offset (y) to transform any range of floats to a texture's standard [0,1] clamp. Sent float (s): s = (data - y) / x. Decoded float (d): d = s * x + y

      Parameters:
      minValue - The lower bound of the float range.
      maxValue - The upper bound of the float range.

      Returns:
      A scalar (x) and offset (y) that can be used to transform the given range of floats to a texture's standard [0,1] clamp.

    • getVisibleU

      public static float getVisibleU()
      Gets the fraction of the U component of ShaderLib's screen texture that is visible on screen.

      Returns:
      The fraction of the U component of ShaderLib's screen texture that is visible on screen.

    • getVisibleV

      public static float getVisibleV()
      Gets the fraction of the V component of ShaderLib's screen texture that is visible on screen.

      Returns:
      The fraction of the V component of ShaderLib's screen texture that is visible on screen.

    • init

      public static void init()
      Starts up ShaderLib; many mods may call this method but only the first will actually do anything.

    • handleMessage

      public static void handleMessage(int source, int type, int id, int severity, String message, boolean includeTrace, boolean suppressIdentical, String title)
      Debug function for printing GL error codes.

      Parameters:
      source - First parameter from KHRDebugCallback
      type - Second parameter from KHRDebugCallback
      id - Third parameter from KHRDebugCallback
      severity - Fourth parameter from KHRDebugCallback
      message - Fifth parameter from KHRDebugCallback
      includeTrace - If true, include stack trace
      suppressIdentical - If true, suppress identical messages
      title - Title to print
      Since:
      1.10.2

    • isForegroundEmpty

      public static boolean isForegroundEmpty(com.fs.starfarer.api.combat.ViewportAPI viewport)
      Returns true if there is no combat engine. Do not use this if the user does not have framebuffer object support! Warning: This function may reset your framebuffer binding to 0! You should save your framebuffer parameters (if any) prior to calling this function!

      Parameters:
      viewport - The viewport in use by the renderer.

      Returns:
      Whether the foreground framebuffer texture is empty or not.

    • isOnScreen

      public static boolean isOnScreen(org.lwjgl.util.vector.Vector2f worldCoords, float radius)
      Checks if a point, bounded by a certain radius, is on screen. Do note that this is only absolutely true if it returns false; if it returns true, the point may still not actually be on screen.

      Parameters:
      worldCoords - The absolute world coordinates of the point.
      radius - How far away from the screen the point can be.

      Returns:
      Whether the point is within the given radius of the viewport.

    • isOnScreen

      public static boolean isOnScreen(org.lwjgl.util.vector.Vector2f worldCoords1, org.lwjgl.util.vector.Vector2f worldCoords2, float radius)
      Checks if a line, bounded by a certain radius, is on screen. Do note that this is only absolutely true if it returns false; if it returns true, the line may still not actually be on screen.

      Parameters:
      worldCoords1 - The absolute world coordinates of one endpoint of the line.
      worldCoords2 - The absolute world coordinates of the other endpoint of the line.
      radius - How far away from the screen the line can be.

      Returns:
      Whether the line is within the given radius of the viewport.

    • loadShader

      public static int loadShader(String vert, String frag)
      Compiles the given shader. Does NOT validate the shader; you must call that function yourself. See the example shaders for how to do this.

      Parameters:
      vert - The vertex shader, given as a String.
      frag - The fragment shader, given as a String.

      Returns:
      The shader program ID corresponding to the newly-compiled shader. Returns 0 on error.

    • makeFramebuffer

      public static int makeFramebuffer(int attachment, int texture, int texWidth, int texHeight, int mipLevel)
      Creates a framebuffer object for the given texture.

      Parameters:
      attachment - Can be EXTFramebufferObject.GL_COLOR_ATTACHMENTi_EXT (i is typically 0), EXTFramebufferObject.GL_DEPTH_ATTACHMENT_EXT, or EXTFramebufferObject.GL_STENCIL_ATTACHMENT_EXT, depending on what kind of texture you use.
      texture - Assumed to be a GL_TEXTURE_2D texture.
      texWidth - Width of texture
      texHeight - Height of texture
      mipLevel - The mipmapping level of the texture to bind to.

      Returns:
      The created FBO ID.

    • screenDraw

      public static void screenDraw(int texture, int textureUnit)
      This function combines the functionalities of copyScreen and drawScreenQuad. This function is meant to be used when the uniform parameters have been bound during the shader's rendering stage.

      Parameters:
      texture - The texture to copy to.
      textureUnit - The texture unit to bind the given texture to.

    • transformScreenToUV

      public static org.lwjgl.util.vector.Vector2f transformScreenToUV(org.lwjgl.util.vector.Vector2f screenCoords)
      Transforms relative screen coordinates to UV texture coordinates.

      Parameters:
      screenCoords - The relative unscaled screen coordinates to transform.

      Returns:
      The UV texture coordinates corresponding to the given relative screen coordinates.

    • transformWorldToScreen

      public static org.lwjgl.util.vector.Vector2f transformWorldToScreen(org.lwjgl.util.vector.Vector2f worldCoords)
      Transforms absolute world coordinates to relative screen coordinates, unscaled.

      Parameters:
      worldCoords - The absolute world coordinates to transform.

      Returns:
      The relative screen coordinates corresponding to the given absolute world coordinates.

    • unitsToUV

      public static float unitsToUV(float units)
      Transforms a distance given in absolute world space units to UV distance. Normalized to square coordinates.

      Parameters:
      units - The absolute world-space distance to transform.

      Returns:
      UV distance representing the given absolute world space units.

    • useBufferARB

      public static boolean useBufferARB()
      Whether to use the ARB_framebuffer_object implementation of FBOs.

      Returns:
      Whether to use the ARB_framebuffer_object implementation of FBOs.

      Since:
      Beta 1.01

    • useBufferCore

      public static boolean useBufferCore()
      Whether to use the core OpenGL 3.0 implementation of FBOs.

      Returns:
      Whether to use the core OpenGL 3.0 implementation of FBOs.

      Since:
      Beta 1.01

    • useBufferEXT

      public static boolean useBufferEXT()
      Whether to use the EXT_framebuffer_object implementation of FBOs.

      Returns:
      Whether to use the EXT_framebuffer_object implementation of FBOs.

      Since:
      Beta 1.01

    • getShipTexture

      public static TextureEntry getShipTexture(com.fs.starfarer.api.combat.ShipAPI ship, TextureData.TextureDataType type)
      Retrieves the most appropriate TextureEntry corresponding to the given ship and texture type. May auto-generate normal maps, if appropriate.

      Parameters:
      ship - Ship to find TextureEntry for.
      type - Texture type to find TextureEntry for.

      Returns:
      TextureEntry corresponding to the given ship/type, or null if not found or unable to auto-generate.

      Since:
      1.4.0

    • getWeaponTexture

      public static TextureEntry getWeaponTexture(com.fs.starfarer.api.combat.WeaponAPI weapon, TextureData.TextureDataType texType, TextureData.ObjectType objType, int frame)
      Retrieves the most appropriate TextureEntry corresponding to the given weapon, texture, and object type. May auto-generate normal maps, if appropriate.

      Parameters:
      weapon - Weapon to find TextureEntry for.
      texType - Texture type to find TextureEntry for.
      objType - Object type to find TextureEntry for. Must be one of: TURRET, TURRET_BARREL, TURRET_UNDER, HARDPOINT, HARDPOINT_BARREL, HARDPOINT_UNDER.
      frame - Animation frame to find TextureEntry for.

      Returns:
      TextureEntry corresponding to the given weapon/type, or null if not found or unable to auto-generate.

      Since:
      1.10.0

    • overrideShipTexture

      public static void overrideShipTexture(com.fs.starfarer.api.combat.ShipAPI ship, String id)
      Overrides a ship's ID for the purposes of determining which TextureEntry to use within shaders (such as lighting). Normally, the ship's Hull ID, D-Parent Hull ID, and then the Base Hull ID are used (in that order).

      Parameters:
      ship - Ship to override ID for.
      id - New ID to use.

      Since:
      1.4.0

    • overrideWeaponTexture

      public static void overrideWeaponTexture(com.fs.starfarer.api.combat.WeaponAPI weapon, String id)
      Overrides a weapon's ID for the purposes of determining which TextureEntry to use within shaders (such as lighting). Normally, the weapon's original ID is used.

      Parameters:
      weapon - Weapon to override ID for.
      id - New ID to use.

      Since:
      1.10.0

    • addMapObject

      public static void addMapObject(MapObjectAPI mapObject)
      Adds an arbitrary material/normal/surface-mapped object to the rendering list.

      Does not check for duplicates.

      Parameters:
      mapObject - The object to add.

      Since:
      1.10.0

    • removeMapObject

      public static void removeMapObject(MapObjectAPI mapObject)
      Removes a mapped object from the rendering list.

      Parameters:
      mapObject - The object to remove.

      Since:
      1.10.0

    • getMapObjects

      public static List<MapObjectAPI> getMapObjects()
      Returns the rendering list of mapped objects.

      Returns:
      The rendering list of mapped objects, or null if unable to do so.

      Since:
      1.10.0