# love.graphics.newShader

Available since LÖVE 0.9.0
It has been renamed from love.graphics.newPixelEffect.

| This function can be slow if it is called repeatedly, such as from love.update or love.draw. If you need to use a specific resource often, create it once and store it somewhere it can be reused! |

Creates a new Shader object for hardware-accelerated vertex and pixel effects. A Shader contains either vertex shader code, pixel shader code, or both.

Shaders are small programs which are run on the video card when drawing. Vertex shaders are run once for each vertex (for example, an image has 4 vertices - one at each corner. A Mesh might have many more.) Pixel shaders are run once for each pixel on the screen which the drawn object touches. Pixel shader code is executed after all the object's vertices have been processed by the vertex shader.

## Function

### Synopsis

    shader = love.graphics.newShader( code )

### Arguments

`string code`
  The pixel shader or vertex shader code, or a filename pointing to a file with the code.

### Returns

`Shader shader`
  A Shader object for use in drawing operations.

## Function

### Synopsis

    shader = love.graphics.newShader( pixelcode, vertexcode )

### Arguments

`string pixelcode`
  The pixel shader code, or a filename pointing to a file with the code.
`string vertexcode`
  The vertex shader code, or a filename pointing to a file with the code.

### Returns

`Shader shader`
  A Shader object for use in drawing operations.

### Notes

The pixelcode and vertexcode arguments can be in any order.

## Shader Language

Shaders are not programmed in Lua, but by using a special shader language instead. The shader language is basically GLSL 1.20 (specs) with a few aliases added for existing types:

GLSL | LÖVE shader language
--- | ---
float | number
sampler2D | Image
uniform | extern
texture2D(tex, uv) | Texel(tex, uv)

Vertex shader code must contain at least one function, named `position`, which is the function that will produce transformed vertex positions of drawn objects in screen-space.

Pixel shader code must contain at least one function, named `effect`, which is the function that will produce the color which is blended onto the screen for each pixel a drawn object touches.

## Pixel Shader Function

### Synopsis

    vec4 effect( vec4 color, Image texture, vec2 texture_coords, vec2 screen_coords )

### Arguments

`vec4 color`
  The drawing color set with love.graphics.setColor or the per-vertex Mesh color.
`Image texture`
  The texture of the image or canvas being drawn.
`vec2 texture_coords`
  Coordinates of the pixel relative to the texture. The y-axis of canvases are inverted. Coordinates (1,1) would be the top right corner of the canvas.
`vec2 screen_coords`
  Coordinates of the pixel on the screen. Pixel coordinates are not normalized (unlike texture coordinates)

### Returns

`vec4 output_color`
  The color of the pixel.

### Notes

If multiple canvases are being rendered to simultaneously (by giving multiple Canvas parameters to love.graphics.setCanvas), you can use the effects function instead of effect in order to output a separate color to each Canvas. It has the following prototype:

    void effects( vec4 color, Image texture, vec2 texture_coords, vec2 screen_coords )
    {
        // love_Canvases is a writable array of vec4 colors. Each index corresponds to a Canvas. If you don't assign a value to all active canvases, bad things might happen.
        love_Canvases[0] = color;
    }

## Vertex Shader Function

### Synopsis

    vec4 position( mat4 transform_projection, vec4 vertex_position )

### Arguments

`mat4 transform_projection`
  The transformation matrix affected by love.graphics.translate and friends combined with the orthographic projection matrix.
`vec4 vertex_position`
  The raw un-transformed position of the current vertex.

### Returns

`vec4 output_pos`
  The final transformed position of the current vertex.

## Notes

Vertex shader code is run for every vertex drawn to the screen (for example, love.graphics.rectangle will produce 4 vertices) and is used to transform the vertex positions from their original coordinates into screen-space, as well as to send information such as per-vertex color and texture coordinate values to the pixel shader.

Pixel shader code is run for every pixel on the screen that a drawn object touches, and is used to produce the color that will be blended onto the screen at that pixel, often by reading from an image. Pixel shaders are sometimes called fragment shaders.

The `varying` keyword can be used to set a value in the vertex shader and have it interpolated in between vertices and passed down to the pixel shader.

Vertex and Pixel shader code can be combined into one file or string if you wrap the vertex-specific code in `#ifdef VERTEX .. #endif` and the pixel-specific code in `#ifdef PIXEL .. #endif`.

## Built-in variables

LÖVE provides several built-in variables for both pixel and vertex shaders. The full list can be found here: Shader Variables.

## Examples

### Create a shader using vertex and pixel shader code which behaves as if no shader is set.

    function love.load()
        local pixelcode = [[
            vec4 effect( vec4 color, Image texture, vec2 texture_coords, vec2 screen_coords )
            {
                vec4 texcolor = Texel(texture, texture_coords);
                return texcolor * color;
            }
        ]]

        local vertexcode = [[
            vec4 position( mat4 transform_projection, vec4 vertex_position )
            {
                return transform_projection * vertex_position;
            }
        ]]

        shader = love.graphics.newShader(pixelcode, vertexcode)
    end

    function love.draw()
        love.graphics.setShader(shader)
        -- draw things
        love.graphics.setShader()
        -- draw more things
    end

### Access the pre-transformed vertex position in the pixel shader with the varying keyword.

#### vertex shader code

    varyingvec4 vpos;

    vec4 position( mat4 transform_projection, vec4 vertex_position )
    {
        vpos = vertex_position;
        return transform_projection * vertex_position;
    }

#### pixel shader code

    varyingvec4 vpos;

    vec4 effect( vec4 color, Image texture, vec2 texture_coords, vec2 screen_coords )
    {
        texture_coords += vec2(cos(vpos.x), sin(vpos.y));
        vec4 texcolor = Texel(texture, texture_coords);
        return texcolor * color;
    }

### Combine the above example into one string or file with the help of #ifdef.

    varyingvec4 vpos;

    #ifdef VERTEX
    vec4 position( mat4 transform_projection, vec4 vertex_position )
    {
        vpos = vertex_position;
        return transform_projection * vertex_position;
    }
    #endif

    #ifdef PIXEL
    vec4 effect( vec4 color, Image texture, vec2 texture_coords, vec2 screen_coords )
    {
        texture_coords += vec2(cos(vpos.x), sin(vpos.y));
        vec4 texcolor = Texel(texture, texture_coords);
        return texcolor * color;
    }
    #endif

## See Also

- love.graphics
- Shader
- love.graphics.setShader
- Shader Variables

##

Category:

- Functions