Use Texture
to pass the sampler2D
uniform value to the shader.
You can create a texture with load
or loadWith
and measure its dimensions with size
.
load : String -> Task Error Texture
Loads a texture from the given url with default options. PNG and JPEG are known to work, but other formats have not been as well-tested yet.
The Y axis of the texture is flipped automatically for you, so it has the same direction as in the clip-space, i.e. pointing up.
If you need to change flipping, filtering or wrapping, you can use
loadWith
.
load url =
loadWith defaultOptions url
Loading a texture can result in two kinds of errors:
LoadError
means the image did not load for some reason. Maybe
it was a network problem, or maybe it was a bad file format.
SizeError
means you are trying to load a weird shaped image.
For most operations you want a rectangle where the width is a power
of two and the height is a power of two. This is more efficient on
the GPU and it makes mipmapping possible. You can use
nonPowerOfTwoOptions
to get things working
now, but it is way better to create power-of-two assets!
size : Texture -> ( Basics.Int, Basics.Int )
Return the (width, height) size of a texture. Useful for sprite sheets or other times you may want to use only a potion of a texture image.
loadWith : Options -> String -> Task Error Texture
Same as load, but allows to set options.
{ magnify : Resize Bigger
, minify : Resize Smaller
, horizontalWrap : Wrap
, verticalWrap : Wrap
, flipY : Basics.Bool
}
Options
describe how to:
magnify
- how to Resize
into a bigger textureminify
- how to Resize
into a smaller texturehorizontalWrap
- how to Wrap
the texture horizontally if the width is not a power of twoverticalWrap
- how to Wrap
the texture vertically if the height is not a power of twoflipY
- flip the Y axis of the texture so it has the same direction
as the clip-space, i.e. pointing up.You can read more about these parameters in the specification.
defaultOptions : Options
Default options for the loaded texture.
{ magnify = linear
, minify = nearestMipmapLinear
, horizontalWrap = repeat
, verticalWrap = repeat
, flipY = True
}
How to resize a texture.
linear : Resize a
Returns the weighted average of the four texture elements that are closest to the center of the pixel being textured.
nearest : Resize a
Returns the value of the texture element that is nearest (in Manhattan distance) to the center of the pixel being textured.
nearestMipmapLinear : Resize Smaller
Chooses the two mipmaps that most closely match the size of the pixel being
textured and uses the nearest
criterion (the texture element nearest to the
center of the pixel) to produce a texture value from each mipmap. The final
texture value is a weighted average of those two values.
nearestMipmapNearest : Resize Smaller
Chooses the mipmap that most closely matches the size of the pixel being
textured and uses the nearest
criterion (the texture element nearest to
the center of the pixel) to produce a texture value.
A mipmap is an ordered set of arrays representing the same image at progressively lower resolutions.
This is the default value of the minify filter.
linearMipmapNearest : Resize Smaller
Chooses the mipmap that most closely matches the size of the pixel being
textured and uses the linear
criterion (a weighted average of the four
texture elements that are closest to the center of the pixel) to produce a
texture value.
linearMipmapLinear : Resize Smaller
Chooses the two mipmaps that most closely match the size of the pixel being
textured and uses the linear
criterion (a weighted average of the four
texture elements that are closest to the center of the pixel) to produce a
texture value from each mipmap. The final texture value is a weighted average
of those two values.
Helps restrict options.magnify
to only allow
linear
and nearest
.
Helps restrict options.magnify
, while also allowing
options.minify
to use mipmapping resizes, like
nearestMipmapNearest
.
Sets the wrap parameter for texture coordinate.
repeat : Wrap
Causes the integer part of the coordinate to be ignored. This is the default value for both texture axis.
clampToEdge : Wrap
Causes coordinates to be clamped to the range 1 2N 1 - 1 2N, where N is the size of the texture in the direction of clamping.
mirroredRepeat : Wrap
Causes the coordinate c to be set to the fractional part of the texture coordinate if the integer part is even; if the integer part is odd, then the coordinate is set to 1 - frac, where frac represents the fractional part of the coordinate.
nonPowerOfTwoOptions : Options
The exact options needed to load textures with weird shapes. If your image width or height is not a power of two, you need these options:
{ magnify = linear
, minify = nearest
, horizontalWrap = clampToEdge
, verticalWrap = clampToEdge
, flipY = True
}