.. _stdlib_texture_scripting:

====================
Texture Scripting
====================

++++++++++++++++++++++
Texture Asset Request
++++++++++++++++++++++

The simplest way to get a texture asset from code is as follows::

    let texture = request_texture("texture.png")

For CubeMaps::

    let cubemap = request_texture("skybox.cubemap")

++++++++++++++++++++++++++++
Texture Creation From Bitmap
++++++++++++++++++++++++++++

Sometimes you may want to fill the texture content from the CPU. You can use the :ref:`Bitmap <function-texture_resource_Bitmap_int_int>` and :ref:`create_texture <function-texture_resource_create_texture_BitmapTexture2Dfloat4Texture2Dfloat2Texture2DfloatTexture2Duint4Texture2Duint2Texture2Duint_TextureDeclaration>` functions for this purpose. See the following code::

    let w = 256
    let h = 256
    var bitmap = Bitmap(w, h) // Create a CPU bitmap of size w x h
    // ... (Fill bitmap with color)
    let texture = create_texture(bitmap, TextureDeclaration(
        filter = TextureFilter Point, // Pixel art style
        sRGB = true, // Mark that it is a color texture
        addressing = TextureAddress Clamp, // Clamp texture coordinates in [0, 1] range
        format = TextureFormat A8R8G8B8, // Use default format for color textures
        generateMipLevels = true // Generate mip levels for using the texture in 3D space
    ))

Note that the bitmap should be filled with color data before creating the texture (it's optional; you can create an empty texture and update it later). You can do this using various functions from the :ref:`Pixel render module <stdlib_pixel_render>`. For example::

    var bitmap = Bitmap(w, h) // Create a CPU bitmap of size w x h
    fill_rect(bitmap, int2(0, 0), int2(w, h), 0xFF0000FF) // Fill the bitmap with blue color
    fill_circle(bitmap, int2(w / 2, h / 2), w / 4, 0xFFFFFF00) // Fill a circle in the center with yellow color

Alternatively, you can fill the bitmap yourself. For example::

    var bitmap = Bitmap(w, h) // Create a CPU bitmap of size w x h
    for (i in 0..h) {
        for (j in 0..w) {
            bitmap.pixels[i * w + j] = 0xFF0000FF // Fill the bitmap with blue color
        }
    }

To update the texture content from the CPU, use the :ref:`update_texture <function-texture_resource_boost_update_texture_BitmapTexture2Dfloat4Texture2Dfloat2Texture2DfloatTexture2Duint4Texture2Duint2Texture2Duint_TextureId_int_int2_int2>` function::

    circle(bitmap, int2(w / 2, h / 2), w / 4, 0xFF000000) // Add a black border to the circle in the center
    update_texture(texture, bitmap)

You can also update a part of the texture instead of the whole texture::

    var bitmap = create_bitmap(32, 32, 0xFF0000FF)
    update_texture(texture, bitmap, 0 /*mip level*/, false /*rebuild mips*/, int2(0, 0) /*offset*/, int2(32, 32) /*size*/)