Game Maker 8.2 DirectX 9.txt

    Game Maker 8.2 DirectX 9
    ========================
    Extension Documentation
    version 2 - July 2023

    Written by Floogle & renex


--------------------------------------------------------------------------------

  General considerations
  
    -> This extension requires the Game Maker 8.2 Network extension. If it is
       not added to the project, it will be automatically added when compiling,
       so make sure your project is compatible with it.
    -> This extension makes extensive in-memory modifications to the Game Runner
       when launching the game, in order to activate DirectX 9. Any extensions
       that inject DirectX state, like Game Maker 8.2 DirectX8, are not
       compatible by definition.
    -> While the extension aims to improve your control over the graphics
       pipeline, making incorrect assumptions or changing the wrong settings
       has the potential to decrease performance. Carefully measure your
       render times, and fine-tune things to find the fastest configuration.
    -> Shaders and Vertex Buffers take a lot of effort to use, so be prepared to
       pour in when you decide to use them. Feel free to reach out to us on the
       Discord server if you run into any issues.


--------------------------------------------------------------------------------

  Application Surface

application_surface_enable(postdraw script id)
    Enables the automatic use and management of an application surface.
    -> The postdraw script will be called when the screen is being composed, so
       any post-processing effects can be applied to it.
application_surface_is_enabled()
    Returns whether the application surface is enabled.
application_surface_get_width(), application_surface_get_height()
    Returns the current size of the application surface.
application_surface_resize(width,height)
    Resizes the application surface.
application_surface_disable()
    Disables the application surface.


--------------------------------------------------------------------------------

  Multiple Render Targets
  
    It is possible to make a shader setup to render to multiple surfaces
    simultaneously. There are a few requirements however:
    -> All surfaces must have the same dimensions, or it behaves strangely.
    -> You have to use a shader, or only the first surface receives output.

surface_set_target_ext(target,surface)
    Binds a surface to a target.
surface_reset_target_ext(target)
    Resets the target and unbinds the surface.

  Notes
  
    -> The default target used normally by Game Maker is target 0.
    -> The HLSL syntax for render targets is as follows:
    
    (pixel shader)
    struct PS_OUTPUT {
        float4 target0: COLOR0;
        float4 target1: COLOR1;
        etc.
    };


--------------------------------------------------------------------------------

  Managed Surfaces
  
    These functions will automatically manage surfaces based on string
    identifiers to prevent errors and memory leaks.

surface_get(name,width,height)
    Returns a managed surface with specified dimensions.
surface_set(name,width,height)
    Returns a managed surface with specified dimensions and also sets
    the target to it.
surface_is_new()
    Returns whether the last call to surface_get or set created a blank surface.
surface_reset()
    Resets the render target and sets the default room or view projection
    if views are enabled.
surface_resize(name,w,h,scale,filter)
    Resizes a managed surface with optional scaling and filtering.
    -> If scaling is disabled, the surface will just be trimmed to fit.
surface_forget(name)
    Forgets a managed surface and frees up the memory used.
surface_forget_all()
    Discards and forgets all managed surfaces.


--------------------------------------------------------------------------------

  Regular Surfaces

surface_discard(id)
    Deletes a surface.
    -> This function prevents errors when the surface doesn't exist.
surface_set_depth(id)
    Sets the depth buffer to use a different surface.

buffer_get_surface(buffer,surface)
    buffer: a gm82net buffer to receive the surface contents.
    surface: a surface to get the contents from.
    This function will retrieve the surface's color data into the buffer.
    -> Each pixel is stored as an u32 0xAABBGGRR color value.
    -> The buffer will be resized to fit the surface's contents
       (new size is width*height*4 bytes).
    -> To get a specific (x,y) pixel from the buffer, the address would be: 
       ((y * width) + x) * 4
    -> To get the alpha and color values of a pixel:
       pixel_u32 = buffer_read_u32(b)
       alpha = argb_get_alpha(pixel_u32)
       color = argb_get_color(pixel_u32)
    -> Do note that this function is very slow, so use it sparingly.
    
buffer_set_surface(buffer,surface)
    buffer: a gm82net buffer with the color data.
    surface: a surface to receive the contents.
    This function will push the buffer's color data to the surface.
    -> The bufer must have enough data in it (at least width*height*4 bytes).
    -> You can pack a color and alpha value into u32s for use with buffers
       using argb_make_color(color,alpha).
    -> Do note that this function is very slow, so use it sparingly.

argb_make_color(color,alpha)
    Turns a color into a u32 the way surface data expects it. Useful for writing
    buffers for use with buffer_set_surface().
argb_get_color(color)
    Gets the color out of a u32 returned by buffer_get_surface().
argb_get_alpha(color)
    Gets the alpha out of a u32 returned by buffer_get_surface().


--------------------------------------------------------------------------------

  D3D Model tools

d3d_model_create_and_load(filename)
    Creates, loads and returns a model from the filename.
    Filename can only be either a g3d model, or a packed g3z model.
d3d_model_load_g3z(model,filename)
    Loads a packed 3d model.
d3d_model_save_g3z(model,filename)
    Saves a packed 3d model.


--------------------------------------------------------------------------------

  Window Functions
  
window_resize_buffer(w,h)
    Resizes the game window's backbuffer to the desired size.
    -> Use this after resizing the game window to get correct pixel
       aspect ratio and crisp rendering.
window_set_fullscreen_ext(enable)
    Experimental exclusive fullscreen support. Very buggy.


--------------------------------------------------------------------------------

  Draw Helpers

draw_make_opaque()
    Makes the current render target fully opaque.
draw_quad(x,y,w,h,tex,[u1,v1,u2,v2])
    Draws a quad at the specified location with the specified texture
    and optional uv coordinates.
    -> Particularly useful for texture generation shaders.
draw_set_blend_alphamode(enable,mode or [src,dest])
    Enable separate blend modes for the alpha channel.
    -> Must be disabled separately from the normal blend mode.

d3d_clear_depth_buffer()
    Clears the depth buffer of the current render target, allowing new geometry
    to be drawn to it with depth occlusion.
d3d_fog_trick([color,amount])
    Enables the fog trick for tinting graphics towards a color.
    -> Only works in orthographic projections. To use in a 3d projection with
    full blend, omit the amount argument.
d3d_get_free_video_memory()
    Gets a rough estimate of free video memory in megabytes. Not very precise,
    always assume a safe margin of a few megabytes.
d3d_set_viewport(x,y,width,height)
    Sets the viewport for drawing as a rectangle region on the screen.
    -> This allows drawing only to a specific part of the screen, e.g. a
       HUD element, textbox, minimap etc.
    -> An appropriate ortho projection fitting the viewport is set for you.
d3d_get_viewport_x(), d3d_get_viewport_y(),
d3d_get_viewport_w(), d3d_get_viewport_h()
    Returns the currently set viewport dimensions.
d3d_light_define_ext(index,type,x,y,z,dx,dy,dz,range,inner_rad,outer_rad,
                  color_diffuse,diffuse_factor,color_specular,specular_factor)
    Sets a 3d light with advanced options.
    index: light number (use small integers)
    type: one of lt_point, lt_spotlight, or lt_sun
    x,y,z: light position (unused for sun lights)
    dx,dy,dz: direction vector (unused for point lights)
    range: maximum light range (unused for sun lights)
    inner_rad: inner aperture angle of spotlights (unused for sun and point)
    outer_rad: outer penumbra angle of spotlights (unused for sun and point)
    color_diffuse: light color
    diffuse_factor: light scaling factor, default 1.
        -> can be used for cool effects f.ex. larger values cause "cel shading".
    color_specular: specular highlight color.
        -> Used for shiny reflections. Set to black to disable.
    specular_factor: exponent factor for specular highlights.
        -> Use values between 10 and 50 depending on the intended effect.
d3d_set_alphatest(enable,value,cm_comparison)
    Sets the alpha test reference value and comparison mode.
    Valid comparison modes include:
    cm_less
        Draws pixels if the alpha value is less than the ref value.
    cm_equal
        Draws pixels if the alpha value is equal to the ref value.
    cm_lessequal
        Draws pixels if the alpha value is less or equal to the ref value.
    cm_greater
        Draws pixels if the alpha value is greater than the ref value.
    cm_greaterequal
        Draws pixels if the alpha value is greater or equal to the ref value.
    cm_notequal
        Draws pixels if the alpha value is different to the ref value.
d3d_set_color_mask(red,green,blue,alpha)
    Enable or disable writing to each color channel.
d3d_set_cull_mode(mode)
    Sets the backface culling method.
    Valid methods include:
    cull_clockwise
        Hides faces with clockwise vertex winding order.
    cull_counterclockwise
        Hides faces with counterclockwise vertex winding order.
    cull_none
        Draw both faces.
d3d_set_depth_scale(near,far)
    Sets the depth buffer comparison scaling.
    -> Useful for drawing in front or behind of existing gemotry.
d3d_set_fill_mode(mode)
    Sets the polygon fill mode.
    Valid modes include:
    fill_normal
        Draw polygons normally.
    fill_points
        Draw only the vertices as points.
    fill_wireframe
        Draw edges as lines.
d3d_set_fog_ext(type,color,start,end)
    Sets the fog mode.
    Valid types include:
    fog_none
        Disable fog.
    fog_table
        Use table fog based on fragment w value. The default fog mode.
    fog_vertex
        Use spherical vertex distance-based fog.
        -> Looks better, but needs small polygons to work correctly.    
d3d_set_point_options(size,scaled,minscale,maxscale,spritemode)
    Sets graphics card options for drawing points.
    size: point size, default 1.
    scaled: whether points will be scaled depending on distance to the camera.
    minscale: minimum point size. can't be bigger than maxscale.
    maxscale: maximum point size. typically limited to 64 in most systems.
    spritemode: draws points using the current texture instead of a solid color.
d3d_set_projection_default()
    Resets to the default orthographic room or current view's
    projection if views are enabled.
d3d_set_projection_simple(x,y,w,h,angle,dollyzoom,
                          depthmin,depthfocus,depthmax,spin)
    Shortcut for setting a simple 3d projection for side-view games.
    angle: horizontal tilt for the view.
    dollyzoom: how much perspective distortion to apply to the scene.
    depthmin: lowest depth to clamp.
    depthfocus: focus point of the projection.
    depthmax: largest depth to clamp.
    spin: angle to spin the camera around the focal point.
d3d_set_viewport(x,y,width,height)
    Sets the current viewport for rendering to a part of the screen.
    Particularly useful for map widgets or scrolling list boxes.
d3d_set_zbias(bias)
    Sets the zbias value used to sort polygons that are close to each other.
    -> The zbias is added to fragment depth when computing overlap,
       to help polygons sort in front or behind of other polygons.
    -> The unit for zbias is in frustum size, so if your znear is 1 and zfar
    is 1000, then to get a zbias of 1 pixel you would set it to 1/999.
d3d_set_zcomp_mode(cm_comparison)
    Sets the z comparison mode when drawing pixels.
    Valid comparison modes include:
    cm_less
        Draws pixels if the z value is less than the zbuffer value.
    cm_equal
        Draws pixels if the z value is equal to the zbuffer value.
    cm_lessequal
        Draws pixels if the z value is less or equal to the zbuffer value.
        This is the default mode.
    cm_greater
        Draws pixels if the z value is greater than the zbuffer value.
    cm_greaterequal
        Draws pixels if the z value is greater or equal to the zbuffer value.
    cm_notequal
        Draws pixels if the z value is different to the zbuffer value.


--------------------------------------------------------------------------------

  Texture Tools

texture_get_max_width(), texture_get_max_height()
    Returns the graphics card's reported maximum texture size.
texture_get_interpolation()
    Returns whether texture interpolation is currently enabled.
texture_set_mode(tm_mode)
    Sets the texture indexing mode.
    -> This only works without a pixel shader.
    Possible modes include:
    tm_regular
        Normal texture indexing mode based on vertex uv coordinates.
    tm_csnormal
        Use the vertex normal, transformed to camera space,
        as the input texture coordinates.
    tm_csposition
        Use the vertex position, transformed to camera space,
        as the input texture coordinates.
    tm_csreflect
        Use the reflection vector, transformed to camera space,
        as the input texture coordinates. The reflection vector is
        computed from the input vertex position and normal vector.
    tm_spheremap
        Use the specified texture coordinates for sphere mapping.
        -> An example is provided with the extension package.
texture_set_repeat_ext(hrepeat,vrepeat,bordercolor)
    Sets the texture repeat method separately for each direction.
    Possible methods include:
    tr_wrap
        Repeats infinitely.
    tr_mirror
        Each repeat is mirrored compared to the last one.
    tr_mirroronce
        Mirrors but only once, then clamps.
    tr_clamp
        No repeating.
    tr_border
        Clamp, but the border color is used outside of the texture region.


--------------------------------------------------------------------------------

  Transformation helpers

d3d_transform_set_matrix(m11,m12,m13,m14,m21,m22,m23,m24,
                         m31,m32,m33,m34,m41,m42,m43,m44)
    Sets the world transform matrix. Parameters are passed in row-major order.
d3d_transform_add_stack_top()
    Applies the transform at the top of the stack to the current transform.
d3d_transform_vertex(x,y,z)
    Applies the current world transform matrix to the passed vertex
    and then returns it in an array using the function name.
    Example:
    d3d_transform_vertex(a,b,c)
    _x=d3d_transform_vertex[0]
    _y=d3d_transform_vertex[1]
    _z=d3d_transform_vertex[2]
d3d_project_vertex(x,y,z)
    Applies the current view-projection transform matrix to the passed vertex
    and then returns it in a 2d array using the function name.
    The returned value is in screen-space coordinates, so you must multiply it
    by the current ortho projection dimensions before usage.
    Example:
    d3d_project_vertex(a,b,c)
    (if the view is 800x600)
    _x=400+400*d3d_project_vertex[0]
    _y=300-300*d3d_project_vertex[1]    
    draw_circle(_x,_y,10,1)
d3d_transform_?(????????)
    Shortcut function for applying many transforms in a sequence.
    Combine which transforms you want:
    x - x rotation
    y - y rotation
    z - z rotation
    s - scale
    t - translate
    -> Any combination of rotations is valid, but scale must be last,
       and translate is mandatory. For example, d3d_transform_yxzst(),
       or d3d_transform_xt() are valid.
d3d_transform_get_determinant()
    Returns the determinant of the current world matrix.
    If negative, the current transform is mirrored.
    This can be useful for determining which cull mode to use.


--------------------------------------------------------------------------------

  Shaders

    Shaders are advanced graphics programs that can modify vertices or fragments
    (more frequently known as pixels or texels) when drawing.
    -> When using shaders, any fixed-function effects such as fog, 3d lighting,
       alpha testing, and things like texture indexing modes will not work.
       Those effects need to be manually implemented as necessary.
    -> A few examples are provided in the examples folder.

    Moreover, the shader version dictates how they need to be used:
    -> You can use a version 2 vertex shader by itself, or with a pixel shader.
    -> You can use a version 2 pixel shader by itself, or with a vertex shader.
    -> You cannot combine version 2 and 3 shaders simultaneously, but you can
       use them interchangeably in the same project.
    -> When using a version 3 shader of either kind, an accompanying shader
       of the other kind is strictly required. Passthrough shaders are supplied
       for this end. For example, when using a version 3 pixel shader, set the
       vertex passthrough.

shader_set(vertex,pixel)
    vertex: a vertex shader.
    pixel: a pixel shader.
    Sets both the vertex and pixel shader. Their model versions should match,
    i.e. a VS2.0 goes with a PS2.0 and a VS3.0 goes with a PS3.0.
shader_vertex_set_passthrough()
    Applies the Shader Model 3.0 passthrough vertex shader.
shader_pixel_set_passthrough()
    Applies the Shader Model 3.0 passthrough pixel shader.
shader_reset()
    Resets both the vertex and the pixel shaders.
shader_draw_shadertoy(shader,x,y,w,h,time)
    shader: a ShaderToy shader from Anvil
    x,y,w,h: position to draw
    time: in seconds
    Draws a ShaderToy shader. Not all shaders can be drawn with this.
    -> This function is not all-encompassing. If a shader doesn't work, copy
       the source code and adapt it to your needs.
    -> For normal shaders, you should probably use draw_quad() instead.

  
  Additional considerations
  
    -> Be mindful of your number types! 1/1024 evaluates to 0 because they're
       integers, while 1.0/1024.0 evaluates to 0.0009765625.
    -> Whenever you modify a position-type vec4, make sure that the w coordinate
       is set to 1.0 before multiplying with a matrix, or your coordinates may
       become completely corrupted.


--------------------------------------------------------------------------------

  Vertex Shaders

    Vertex shaders are graphics programs that can modify the properties of
    polygon vertices as they're rendered. They're most commonly seen simply
    moving vertices from world space to screen space. They can also be used to
    perform cheap 3D lighting, fog calculations, and morphing such as model
    bone animation.

shader_vertex_create_file(filename)
    filename: a file name.
    returns: the vertex shader.
    Creates a new vertex shader from a .vs2 or .vs3 file created by Anvil.
    -> A reference to the new vertex shader is returned.
    -> Don't call this multiple times. It's recommended to call this once for
       each shader during a load screen or game start.
shader_vertex_create_base64(string)
    string: a base64 string containing a shader.
    returns: the vertex shader.
    Creates a new vertex shader from a base64 string created by Anvil.
    -> A reference to the new vertex shader is returned.
    -> Don't call this multiple times. It's recommended to call this once for
       each shader during a load screen or game start.
shader_vertex_create_buffer(buffer)
    buffer: a gm82net buffer containing a vertex shader.
    returns: the vertex shader.
    Creates a new vertex shader from a gm82net buffer.
    -> A reference to the new vertex shader is returned.
    -> Don't call this multiple times. It's recommended to call this once for
       each shader during a load screen or game start.
shader_vertex_set(shader)
    shader: a vertex shader.
    Sets a given vertex shader.
    -> Any matrix uniforms must be manually passed using the uniform functions.
shader_vertex_reset()
    Resets to the default vertex shader.
shader_vertex_uniform_f(uniform,...)
    uniform: a uniform name, or its register ID
    Sets one or multiple float uniforms in the vertex shader.
    -> Up to 15 values are accepted. Passing up to 4 values will fill one float4
       register. Passing more will fill subsequent float4 registers.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 256 numerical register IDs, from 0 through 255.
    -> This function should be called after setting the relevant vertex shader.
shader_vertex_uniform_b(uniform,...)
    uniform: a uniform name, or its register ID
    Sets one or multiple boolean uniforms in the vertex shader.
    -> Up to 15 values are accepted.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 16 numerical register IDs, from 0 through 15.
    -> This function should be called after setting the relevant vertex shader.
shader_vertex_uniform_i(uniform,...)
    uniform: a uniform name, or its register ID
    Sets one or multiple integer uniforms in the vertex shader.
    -> Up to 15 values are accepted. Passing up to 4 values will fill one int4
       register. Passing more will fill subsequent int4 registers.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 16 numerical register IDs, from 0 through 15.
    -> This function should be called after setting the relevant vertex shader.
shader_vertex_uniform_color(uniform,color,[alpha])
    uniform: a uniform name, or its register ID
    color: a Game Maker-formatted color, e.g. c_red
    alpha: an alpha value, from 0 (transparent) to 1 (opaque)
    Sets a color uniform in the vertex shader.
    -> This is interpreted as a float uniform. In the shader, the result is a
       RGBA float4 register with values ranging from 0 to 1.
    -> See shader_vertex_uniform_f for other considerations.
shader_vertex_uniform_get_address(uniform)
    uniform: a uniform name
    Gets the register index for a given uniform in the vertex shader.
    -> If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> This function should be called after setting the relevant vertex shader.
shader_vertex_uniform_matrix(uniform,mtx_type)
    uniform: a uniform name, or its register ID
    mtx_type: one of the mtx_constants
    Copies the given matrix into the matrix uniform in the vertex shader.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 256 numerical register IDs, but matrices take up 4 registers,
       so only registers 0 through 252 are valid.
    -> This function should be called after setting the relevant vertex shader.
    -> Accepted matrices are: mtx_world, mtx_view, mtx_projection,
       mtx_world_view, mtx_view_projection, mtx_world_view_projection
    -> Notice that the world matrix will change whenever a transform is applied.
shader_vertex_uniform_f_buffer(uniform,buffer)
    uniform: a uniform name, or its register ID
    buffer: a gm82net containing the uniform data
    Copies the given buffer data into the float uniform in the vertex shader.
    -> Buffers must contain sets of 4 32-bit floats.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 256 numerical register IDs, from 0 through 255.
    -> This function should be called after setting the relevant vertex shader.
shader_vertex_uniform_b_buffer(uniform,buffer)
    uniform: a uniform name, or its register ID
    buffer: a gm82net containing the uniform data
    Copies the given buffer data into the boolean uniform in the vertex shader.
    -> Buffers must contain sets of 4 32-bit booleans (0 or 1 integers).
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 256 numerical register IDs, from 0 through 255.
    -> This function should be called after setting the relevant vertex shader.
shader_vertex_uniform_i_buffer(uniform,buffer)
    uniform: a uniform name, or its register ID
    buffer: a gm82net containing the uniform data
    Copies the given buffer data into the integer uniform in the vertex shader.
    -> Buffers must contain sets of 4 32-bit integers.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 256 numerical register IDs, from 0 through 255.
    -> This function should be called after setting the relevant vertex shader.
texture_set_stage_vertex(sampler,texture)
    sampler: a uniform name, or its sampler ID
    Sets the given texture as a uniform in the vertex shader.
    -> Sampler uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> This function should be called after setting the relevant vertex shader.
texture_set_stage_vertex_interpolation(sampler,linear)
    sampler: a uniform name, or its sampler ID
    linear: true is bilinear, false is nearest neighbour
    Sets the interpolation mode for a given sampler.
    -> Sampler uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> This function should be called after setting the relevant vertex shader.
texture_set_stage_vertex_repeat(sampler,hrepeat,vrepeat,bordercolor)
    Sets the texture repeat method for a given sampler in the vertex shader,
    separately for each direction and optionally with a border color.
    -> Arguments are similar to texture_set_repeat_ext.
    -> Sampler uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> This function should be called after setting the relevant vertex shader.
shader_vertex_destroy(shader)
    shader: a vertex shader
    Deletes a given vertex shader from memory.


--------------------------------------------------------------------------------

  Pixel Shaders
  
    Pixel shaders (also sometimes referred to as fragment shaders) can modify
    each screen-pixel of a polygon as it's rasterized. Common applications
    include color correction, texture distortions, ray marching, and procedural
    texture generation and processing.

shader_pixel_create_file(filename)
    filename: a file name.
    returns: the pixel shader.
    Creates a new pixel shader from a .vs2 or .vs3 file created by Anvil.
    -> A reference to the new pixel shader is returned.
    -> Don't call this multiple times. It's recommended to call this once for
       each shader during a load screen or game start.
shader_pixel_create_base64(string)
    string: a base64 string containing a shader.
    returns: the pixel shader.
    Creates a new pixel shader from a base64 string created by Anvil.
    -> A reference to the new pixel shader is returned.
    -> Don't call this multiple times. It's recommended to call this once for
       each shader during a load screen or game start.
shader_pixel_create_buffer(buffer)
    buffer: a gm82net buffer containing a pixel shader.
    returns: the pixel shader.
    Creates a new pixel shader from a gm82net buffer.
    -> A reference to the new pixel shader is returned.
    -> Don't call this multiple times. It's recommended to call this once for
       each shader during a load screen or game start.
shader_pixel_set(shader)
    shader: a pixel shader.
    Sets a given pixel shader.
shader_pixel_reset()
    Resets to the default pixel shader.
shader_pixel_uniform_f(uniform,...)
    uniform: a uniform name, or its register ID
    Sets one or multiple float uniforms in the pixel shader.
    -> Up to 15 values are accepted. Passing up to 4 values will fill one float4
       register. Passing more will fill subsequent float4 registers.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 256 numerical register IDs, from 0 through 255.
    -> This function should be called after setting the relevant pixel shader.
shader_pixel_uniform_b(uniform,...)
    uniform: a uniform name, or its register ID
    Sets one or multiple boolean uniforms in the pixel shader.
    Up to 15 values are accepted.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 16 numerical register IDs, from 0 through 15.
    -> This function should be called after setting the relevant pixel shader.
shader_pixel_uniform_i(uniform,...)
    uniform: a uniform name, or its register ID
    Sets one or multiple integer uniforms in the pixel shader.
    -> Up to 15 values are accepted. Passing up to 4 values will fill one int4
       register. Passing more will fill subsequent int4 registers.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 16 numerical register IDs, from 0 through 15.
    -> This function should be called after setting the relevant pixel shader.
shader_pixel_uniform_color(uniform,color,[alpha])
    uniform: a uniform name, or its register ID
    color: a Game Maker-formatted color, e.g. c_red
    alpha: an alpha value, from 0 (transparent) to 1 (opaque)
    Sets a color uniform in the pixel shader.
    -> This is interpreted as a float uniform. In the shader, the result is a
       RGBA float4 register with values ranging from 0 to 1.
    -> See shader_pixel_uniform_f for other considerations.
shader_pixel_uniform_get_address(uniform)
    uniform: a uniform name
    Gets the register index for a given uniform in the pixel shader.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> This function should be called after setting the relevant pixel shader.
shader_pixel_uniform_matrix(uniform,mtx_type)
    uniform: a uniform name, or its register ID
    mtx_type: one of the mtx_constants
    Copies the given matrix into the given float4x4 uniform in the pixel shader.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 256 numerical register IDs, but matrices take up 4 registers,
       so only registers 0 through 252 are valid.
    -> This function should be called after setting the relevant pixel shader.
    -> Accepted matrices are: mtx_world, mtx_view, mtx_projection,
       mtx_world_view, mtx_view_projection, mtx_world_view_projection
    -> Notice that the world matrix will change whenever a transform is applied.
shader_pixel_uniform_f_buffer(uniform,buffer)
    uniform: a uniform name, or its register ID
    buffer: a gm82net containing the uniform data
    Copies the given buffer data into the float uniform in the pixel shader.
    -> Buffers must contain sets of 4 32-bit floats.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 256 numerical register IDs, from 0 through 255.
    -> This function should be called after setting the relevant pixel shader.
shader_pixel_uniform_b_buffer(uniform,buffer)
    uniform: a uniform name, or its register ID
    buffer: a gm82net containing the uniform data
    Copies the given buffer data into the boolean uniform in the pixel shader.
    -> Buffers must contain sets of 4 32-bit booleans (0 or 1 integers).
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 256 numerical register IDs, from 0 through 255.
    -> This function should be called after setting the relevant pixel shader.
shader_pixel_uniform_i_buffer(uniform,buffer)
    uniform: a uniform name, or its register ID
    buffer: a gm82net containing the uniform data
    Copies the given buffer data into the integer uniform in the pixel shader.
    -> Buffers must contain sets of 4 32-bit integers.
    -> Uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> There are 256 numerical register IDs, from 0 through 255.
    -> This function should be called after setting the relevant pixel shader.
texture_set_stage(sampler,texture)
    sampler: a uniform name, or its sampler ID
    Sets the given texture as a uniform in the pixel shader.
    -> Sampler uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Struct and array accessors are also accepted, e.g. "a.b[5]".
    -> This function should be called after setting the relevant pixel shader.
texture_set_stage_interpolation(sampler,linear)
    sampler: a uniform name, or its sampler ID
    linear: true is bilinear, false is nearest neighbour
    Sets the interpolation mode for a given sampler in the pixel shader.
    -> Sampler uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> This function should be called after setting the relevant pixel shader.
texture_set_stage_repeat(sampler,hrepeat,vrepeat,bordercolor)
    Sets the texture repeat method for a given sampler in the pixel shader,
    separately for each direction and optionally with a border color.
    -> Sampler uniform names are accepted as strings.
       If a name is invalid, an error will be thrown.
    -> Arguments are similar to texture_set_repeat_ext.
    -> This function should be called after setting the relevant pixel shader.
shader_pixel_destroy(shader)
    shader: a pixel shader
    Deletes a given pixel shader from memory.


--------------------------------------------------------------------------------

  Vertex, Index, and Instance Buffers, and their Formats
  
    Vertex buffers are memory streams of vertex data. They're what d3d models
    are made of internally, but instead you can choose whatever format you want
    to store your vertices as.
    
    Before using a vertex buffer, remember that you will need a Format to go
    with it, and also a vertex shader that will expect that format.
    Additionally, you can use index buffers and instanced rendering to further
    speed up drawing by up to a factor of 10000%. More on that later.


  Vertex Formats
  
    Formats are instruction sets for DirectX so that it knows how your vertex
    buffers are formatted. Formats are required for using any of the following
    advanced rendering features.

vertex_format_create_default()
    Creates and returns the default format used by game maker:
    vf_type_float3,vf_usage_position;
    vf_type_float3,vf_usage_normal;
    vf_type_float4,vf_usage_color;
    vf_type_float2,vf_usage_texcoord;
    All usages are assigned to slot 0.
vertex_format_create_simple(vf_usage_...)
    Creates and returns a format built from a list of vf_usage constants.
    All usages are assigned to slot 0.

vertex_format_begin()
    Starts describing a custom format.
vertex_format_add_custom(vf_type_...,vf_usage_...,slot)
    Adds a completely custom type to the format. When using a format slot for
    arbitrary data (f.ex. tile index in an atlas), use a vf_usage_arbitrary.
    The slot index defines which format slot the usage is bound to. More on
    format slots later.
vertex_format_add_position(slot)
    Adds a standard position component to the format:
    vf_type_float3,vf_usage_position;
vertex_format_add_normal(slot)
    Adds a standard normal component to the format:
    vf_type_float3,vf_usage_normal;
vertex_format_add_color(slot)
    Adds a standard color component to the format:
    vf_type_float4,vf_usage_color;
vertex_format_add_texcoord(slot)
    Adds a standard texture coordinate component to the format:
    vf_type_float2,vf_usage_texcoord;
vertex_format_end()
    Finishes a custom format description and returns a format index for use.

vertex_format_get_size(format,slot)
    Returns the size in bytes of one of the format's slots.
    This advanced function is used for figuring out vertex buffer stride for
    controlling indexed and instanced rendering.
vertex_format_delete(format)
    Deletes the format and frees the memory associated with it.

    
  Vertex Buffers

    Vertex buffers are memory streams containing vertex data for describing
    polygons directly in the video ram. They're much faster than d3d models and
    primitives when used correctly. There are a number of functions to create
    and manage vertex buffers:

vertex_buffer_create(buffer,format,slot)
    Creates a vbuffer from a gm82net buffer using the supplied format and slot
    as a template.
vertex_buffer_bind(vbuffer,slot)
    Binds a vbuffer to a specific buffer slot. More on slots later.
vertex_buffer_get_size(vbuffer)
    Returns the size of the vbuffer in bytes.
vertex_buffer_draw(vbuffer,format,primitive,texture,[ibuffer])
    Draws a vbuffer with a format, a primitive type, a texture, and optionally
    an index buffer. More on this later.
vertex_buffer_delete(vbuffer)
    Deletes a vbuffer and frees all memory associated with it.


  Index Buffers

    Index buffers are auxiliary buffers which are used to describe how vertices
    are connected to form primitives. The use of an index buffer can reduce the
    total amount of memory required by meshes, and is required for indexed and
    instanced rendering modes.

index_buffer_create(buffer,ib_...)
    Creates an index buffer from a gm82net buffer, using the specified format
    constant (either ib_format_16 using buffer u16, or ib_format_32 using
    buffer u32).
index_buffer_delete(ibuffer)
    Deletes an ibuffer and frees all memory associated with it.


  Indexed rendering
  
    Indexed rendering is a different way to render, using a separate buffer to
    instruct the system on how to combine vertices into primitives. Indexed
    rendering is also a required step for Instanced Rendering, described later.
    
    An example of indexed rendering is provided in the examples folder.
  

  Instance Buffers
  
    Instance buffers are used for instanced rendering mode, which is a way to
    efficiently draw many copies of a mesh with just one draw call.

vertex_instance_set(instbuffer,format,slot)
    Configures an instance buffer for instanced rendering, using a format and
    slot. Further indexed rendering will use the instance buffer.
vertex_instance_reset()
    Resets the instanced rendering options. Further indexed rendering will not
    use instanced rendering.


  Instanced rendering

    An instance buffer contains custom data that can be used to modify each
    instance drawn, such as position, rotation, color etc. All of the modifying
    work is done in an accompanying vertex shader, which is required.
    
    Instanced rendering can be hundreds of times faster than drawing normally,
    and an example of instanced rendering is provided in the examples folder.


  Miscellaneous functions
  
color_to_d3dcolor(color,alpha)
    Converts a color into a u32 formatted the way DirectX expects it. Useful
    for writing vertex buffers.


--------------------------------------------------------------------------------