Skip to content

figure_texture ​

figure_texture, RGBA images on the GPU, drawn by ig_image and ip_image, and PNG or JPEG files read into pixels.

A texture is the one retained resource of FIGURE: the image lives on the GPU between frames, so the program uploads pixels only when they change, not every frame.

fortran
 type(texture_object) :: tex
 integer(int8)        :: rgba(4, 640, 480)    ! rgba(:, i, j): pixel (i, j), channels R, G, B, A
 call tex%init(640, 480)
 call tex%update(rgba)                       ! one upload, straight from the array: no copy
 ... call ig_image(tex) or ip_image('field', tex, xmin, xmax, ymin, ymax) every frame
 call tex%destroy()

Pixels are integer(int8) bytes: values 128-255 are stored as their two's-complement bit pattern (-128..-1), so int(v - merge(256, 0, v > 127), int8) converts a 0-255 integer v. rgba(:, i, j) is the pixel in column i and row j: in Fortran's column-major order that is exactly OpenGL's layout (channels, then a row, then the next row), so the array is uploaded in place.

fig_read_image(path, rgba) reads a PNG or a JPEG file into such an array (allocated to rgba(4, width, height), row 1 the file's top row); it draws nothing, so a task may call it. tex%load(path) reads a file into a texture.

Source: src/lib/figure_texture.F90

Dependencies

Contents ​

Derived Types ​

texture_object ​

An RGBA texture, 8 bits per channel.

No finaliser: an intrinsic assignment or a function result would finalise a copy and destroy the texture the original still uses. Call destroy (or let app%destroy release the textures left).

Components

NameTypeAttributesDescription
idinteger(kind=c_long_long)ImTextureID; 0: no texture.
nxinteger(kind=int32)Width [pixels].
nyinteger(kind=int32)Height [pixels].

Type-Bound Procedures

NameAttributesDescription
initpass(self)Create the texture.
updatepass(self)Upload all its pixels.
loadpass(self)Create it from a PNG or JPEG file.
destroypass(self)Release it.
widthpass(self)Width [pixels].
heightpass(self)Height [pixels].
is_initializedpass(self)Whether it exists.

Subroutines ​

init ​

Create a width x height texture (contents undefined until update); an existing one is destroyed first.

Attributes: recursive

fortran
subroutine init(self, width, height, smooth, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(texture_object)inoutTexture.
widthinteger(kind=int32)inWidth [pixels].
heightinteger(kind=int32)inHeight [pixels].
smoothlogicalinoptionalLinear filtering when scaled (default: nearest, sharp pixels).
statinteger(kind=int32)outoptionalStatus.

Call graph

update ​

Upload all the pixels, rgba(4, width, height), in place (no copy); the array may change after the call.

Attributes: recursive

fortran
subroutine update(self, rgba, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(texture_object)inTexture.
rgbainteger(kind=int8)incontiguous, targetPixels: rgba(:, i, j) = R, G, B, A of (i, j).
statinteger(kind=int32)outoptionalStatus.

Call graph

load ​

Create the texture from a PNG or JPEG file, its size the image's, and upload the pixels (fig_read_image, then init and update); an existing texture is replaced. On a failure to read the file the texture is left as it was. Main thread only, as init.

Attributes: recursive

fortran
subroutine load(self, path, smooth, stat)

Arguments

NameTypeIntentAttributesDescription
selfclass(texture_object)inoutTexture.
pathcharacter(len=*)inFile name (UTF-8).
smoothlogicalinoptionalLinear filtering when scaled (default: nearest).
statinteger(kind=int32)outoptionalStatus: as fig_read_image, then as init.

Call graph

destroy ​

Release the texture (safe in any state). From a task: refused, the texture kept (the GPU texture belongs to the main thread), the task's status FIG_ERR_STATE naming texture_object%destroy.

Attributes: recursive

fortran
subroutine destroy(self)

Arguments

NameTypeIntentAttributesDescription
selfclass(texture_object)inoutTexture.

Call graph

fig_read_image ​

Read a PNG or JPEG file into RGBA pixels: rgba is allocated to rgba(4, width, height), rgba(:, i, j) the red, green, blue and alpha bytes of the pixel in column i (left to right) and row j (top to bottom, the file's order), the layout tex%update takes. A grey image gives R = G = B; an image without alpha gives A = 255 (-1_int8). Draws nothing: a task may call it. On a failure rgba is left unallocated.

Attributes: recursive

fortran
subroutine fig_read_image(path, rgba, stat)

Arguments

NameTypeIntentAttributesDescription
pathcharacter(len=*)inFile name (UTF-8).
rgbainteger(kind=int8)outallocatablePixels: rgba(:, i, j) = R, G, B, A of (i, j).
statinteger(kind=int32)outoptionalread, FIG_ERR_ARGUMENT if it is not a PNG or a JPEG, or cannot be decoded.

Call graph

read_image ​

fig_read_image for the procedure name, which starts the message of a failure.

Attributes: recursive

fortran
subroutine read_image(name, path, rgba, stat)

Arguments

NameTypeIntentAttributesDescription
namecharacter(len=*)inThe public procedure.
pathcharacter(len=*)inFile name (UTF-8).
rgbainteger(kind=int8)outallocatablePixels.
statinteger(kind=int32)outStatus.

Call graph

Functions ​

width ​

Width [pixels] (0 when not initialized).

Attributes: pure

Returns: integer(kind=int32)

fortran
function width(self) result(w)

Arguments

NameTypeIntentAttributesDescription
selfclass(texture_object)inTexture.

Call graph

height ​

Height [pixels] (0 when not initialized).

Attributes: pure

Returns: integer(kind=int32)

fortran
function height(self) result(h)

Arguments

NameTypeIntentAttributesDescription
selfclass(texture_object)inTexture.

Call graph

is_initialized ​

Whether the texture exists.

Attributes: pure

Returns: logical

fortran
function is_initialized(self) result(yes)

Arguments

NameTypeIntentAttributesDescription
selfclass(texture_object)inTexture.

Call graph

texture_ref ​

The ImTextureRef of a texture, for the figure_* modules that draw it (not exported by figure).

Attributes: pure

Returns: type(im_texture_ref)

fortran
function texture_ref(tex) result(ref)

Arguments

NameTypeIntentAttributesDescription
textype(texture_object)inTexture.

Call graph

Released under the MIT licence.