Image API documentation

Functions for creating image objects.

Version: alpha

RECORDS
image.astc_header	ASTC image header
image.load_buffer_result	Loaded buffer image data
image.load_options	Image loading options
image.load_result	Loaded string image data

ENUMS
image.TYPE	Image types

FUNCTIONS
image.get_astc_header()	get the header of an .astc buffer
image.load()	load image from buffer
image.load_buffer()	load image from a string into a buffer object

Records

image.astc_header

ASTC image header

FIELDS

`width`	`integer`	Image width.
`height`	`integer`	Image height.
`depth`	`integer`	Image depth.
`block_size_x`	`integer`	Block size on the x-axis.
`block_size_y`	`integer`	Block size on the y-axis.
`block_size_z`	`integer`	Block size on the z-axis.

image.load_buffer_result

Loaded buffer image data

FIELDS

`width`	`integer`	Image width.
`height`	`integer`	Image height.
`type`	`image.TYPE`	Image type.
`buffer`	`buffer_data`	Script buffer containing the decompressed image data.

image.load_options

Image loading options

FIELDS

`[premultiply_alpha]`	`boolean`	Whether to premultiply alpha into the color components. Defaults to `false`.
`[flip_vertically]`	`boolean`	Whether to flip the image contents vertically. Defaults to `false`.

image.load_result

Loaded string image data

FIELDS

`width`	`integer`	Image width.
`height`	`integer`	Image height.
`type`	`image.TYPE`	Image type.
`buffer`	`string`	Raw image data.

Enums

image.TYPE

image.TYPE: string

Image types

VALUES

`image.TYPE_RGB`	RGB image type.
`image.TYPE_RGBA`	RGBA image type.
`image.TYPE_LUMINANCE`	Luminance image type.
`image.TYPE_LUMINANCE_ALPHA`	Luminance-alpha image type.

Functions

image.get_astc_header()

image.get_astc_header(buffer:string)→header:image.astc_header|nil

get the header of an .astc buffer

PARAMETERS

buffer string .astc file data buffer

RETURNS

header image.astc_header
nil header, or nil if the buffer is not a valid ASTC image

EXAMPLES

How to get the block size and dimensions from a .astc file

local s = sys.load_resource("/assets/cat.astc")
local header = image.get_astc_header(s)
pprint(s)

image.load()

image.load(buffer:string, [options:boolean|image.load_options])→image:image.load_result|nil

Load image (PNG or JPEG) from buffer.

PARAMETERS

`buffer`	`string`	image data buffer
`[options]`	`boolean` `image.load_options`	Optional loading parameters. A boolean is accepted for backwards compatibility and controls `premultiply_alpha`.

RETURNS

image image.load_result
nil loaded image, or nil if loading fails

EXAMPLES

How to load an image from an URL and create a GUI texture from it:

local imgurl = "http://www.site.com/image.png"
http.request(imgurl, "GET", function(self, id, response)
        local img = image.load(response.response)
        local tx = gui.new_texture("image_node", img.width, img.height, img.type, img.buffer)
    end)

image.load_buffer()

image.load_buffer(buffer:string, [options:boolean|image.load_options])→image:image.load_buffer_result|nil

Load image (PNG or JPEG) from a string buffer.

PARAMETERS

`buffer`	`string`	image data buffer
`[options]`	`boolean` `image.load_options`	Optional loading parameters. A boolean is accepted for backwards compatibility and controls `premultiply_alpha`.

RETURNS

image image.load_buffer_result
nil loaded image, or nil if loading fails

EXAMPLES

Load an image from an URL as a buffer and create a texture resource from it:

local imgurl = "http://www.site.com/image.png"
http.request(imgurl, "GET", function(self, id, response)
        local img = image.load_buffer(response.response, { flip_vertically = true })
        local tparams = {
            width  = img.width,
            height = img.height,
            type   = graphics.TEXTURE_TYPE_2D,
            format = graphics.TEXTURE_FORMAT_RGBA }

        local my_texture_id = resource.create_texture("/my_custom_texture.texturec", tparams, img.buffer)
        -- Apply the texture to a model
        go.set("/go1#model", "texture0", my_texture_id)
    end)