Render Reference - Min/Mag Texture Filters

<cat>Dev</cat>
<title>Render Reference - Min/Mag Texture Filters</title>
# Render Library References
These pages seek to provide helpful insight into the groups of functions provided by the <page text="Render Library">render</page>.

The major function groups are:
* <page text="Beams">render_beams</page>
* **Minification and Magnification Texture Filters**
* <page text="Render Targets">render_rendertargets</page>
	* <page text="Stencils">render_stencils</page>

# What are Min(ification) and Mag(nification) Filters?
Minification and Magnification filters are a feature of DirectX 9, which the Source Engine (and Garry's Mod, by extension) uses for its graphics rendering.

These two filters handle the very common situation where an image of some kind (a <page text="Texture">ITexture</page> or <page>Material</page> in the Source Engine) needs to be drawn at either a larger or smaller size than its natural size.  In either case, there has to be some logic to tell the graphics system how it should stretch (Magnify) or compress (Minify) the image to make it fit the desired size.

In some situations like, for example, a pixel-art game, you may want low resolution pixel-art to be drawn at a much higher resolution on a modern display without the graphics system attempting to smooth the pixels as it stretches them, because smoothing would ruin the pixel-art look of the textures.

In other cases you might have a high resolution image, like a logo, that needs to be minified so that it can be drawn much smaller for something like a business card, or a HUD element without looking like it's missing key details of the design.

While it's not always necessary to make a specific minification or magnification filter choice for everything drawn to the screen, it can make a huge difference in the situations where it *is* needed.

# What Functions are There?
## Magnification
* <page text="render.PushFilterMag( number TEXFILTER )">render.PushFilterMag</page> - Add magnification filtering with a given filter
* <page text="render.PopFilterMag()">render.PopFilterMag</page> - Remove the most recent magnification filter

## Minification
* <page text="render.PushFilterMin( number TEXFILTER )">render.PushFilterMin</page> - Add minification filtering with a given filter
* <page text="render.PopFilterMin()">render.PopFilterMin</page> - Remove the most recent minification filter

# What Filters are There?

There are four (4) filters available via the <page text="Texture Filtering (TEXFILTER)">enums/TEXFILTER</page> enums:

0. <page text="None">Enums/TEXFILTER#TEXFILTERNONE</page> - This produces a pixelated appearance, similar to Point filtering.
1. <page text="Point">Enums/TEXFILTER#TEXFILTERPOINT</page> - This produces a pixelated look.  For more detailed info, [see this page.](https://learn.microsoft.com/en-us/windows/win32/direct3d9/nearest-point-sampling)
2. <page text="Linear">Enums/TEXFILTER#TEXFILTERLINEAR</page> - This produces a smoothed look.  For more detailed info, [see this page.](https://learn.microsoft.com/en-us/windows/win32/direct3d9/linear-texture-filtering)
3. <page text="Anisotropic">Enums/TEXFILTER#TEXFILTERANISOTROPIC</page> - This filter smooths textures based in part on their angle relative to the camera.  For more detailed info, [see this page](https://learn.microsoft.com/en-us/windows/win32/direct3d9/anisotropic-texture-filtering)

For a demonstration of how each filter looks, see the example output below.

# Usage Example

<example>
	<description>
		The following example provides a simple demonstration of each filter on both a magnified and minified version of an image.	
	</description>
	<code>
-- Calling Material() every frame is quite expensive
-- So we call it once, outside of any hooks, and cache the result in a local variable
local ourMat = Material( "entities/sent_ball.png" )
local sizeBig = 500
local sizeSmall = 100
local pos = 100

local filters = {}
filters[ TEXFILTER.NONE ] = "NONE"
filters[ TEXFILTER.POINT ] = "POINT"
filters[ TEXFILTER.LINEAR ] = "LINEAR"
filters[ TEXFILTER.ANISOTROPIC ] = "ANISOTROPIC"

hook.Add( "HUDPaint", "PutAUniqueHookNameHere", function()
	surface.SetDrawColor( 255, 255, 255, 255 ) -- Set the drawing color
	surface.SetMaterial( ourMat ) -- Use our cached material

	-- Show each filter for 1 second each 
	-- (TEXFILTER enums correspond to integer numbers)
	local filter = math.floor( CurTime() % 4 )

	render.PushFilterMag( filter )
	render.PushFilterMin( filter )

	-- Actually draw the rectangle with a magnification filter
	surface.DrawTexturedRect( pos, pos, sizeBig, sizeBig )

	-- Actually draw the rectangle with a minification filter
	surface.DrawTexturedRect( pos + sizeBig + 1, pos, sizeSmall, sizeSmall )

	render.PopFilterMin()
	render.PopFilterMag()

	draw.SimpleText( filters[ filter ], "ChatFont", pos + 1, pos + 1, color_white )

end )
	</code>
<output><image src="70c/8dc3a1e216d7866.gif" size="1659874" name="hl2_eKnL9y0wEk.gif" /></output>

</example>

Render Reference - Min/Mag Texture Filters

Account Management

Special Pages

Wiki List

Garry's Mod Wiki