Macros | Typedefs | Enumerations | Functions
Materials

Macros

#define TANVASTOUCH_ERROR_MATERIAL   (7u << 16u)
 
#define TANVASTOUCH_ERROR_MATERIAL_TOO_FEW_UVS   TANVASTOUCH_AS(int, (TANVASTOUCH_ERROR_MATERIAL | 1u))
 
#define TANVASTOUCH_ERROR_MATERIAL_INVALID_TEXTURE_INDEX   TANVASTOUCH_AS(int, (TANVASTOUCH_ERROR_MATERIAL | 2u))
 

Typedefs

typedef enum tanvastouch_wrap_mode_e tanvastouch_wrap_mode
 

Enumerations

enum  tanvastouch_wrap_mode_e { tanvastouch_wrap_mode_clamp = 0, tanvastouch_wrap_mode_tile = 1 }
 

Functions

TANVASTOUCH_API int tanvastouch_create_material (tanvastouch_ctx *ctx, tanvastouch_resource_id *p_material_id)
 
TANVASTOUCH_API int tanvastouch_destroy_material (tanvastouch_ctx *ctx, tanvastouch_resource_id material_id)
 
TANVASTOUCH_API int tanvastouch_add_material_texture (tanvastouch_ctx *ctx, tanvastouch_resource_id material_id, int index, tanvastouch_resource_id texture_id)
 
TANVASTOUCH_API int tanvastouch_remove_material_texture (tanvastouch_ctx *ctx, tanvastouch_resource_id material_id, int index)
 
TANVASTOUCH_API int tanvastouch_get_material_texture (tanvastouch_ctx *ctx, tanvastouch_resource_id material_id, int index, tanvastouch_resource_id *p_texture_id)
 
TANVASTOUCH_API int tanvastouch_set_material_uv (tanvastouch_ctx *ctx, tanvastouch_resource_id material_id, int index, float *p_uv)
 
TANVASTOUCH_API int tanvastouch_get_material_uv (tanvastouch_ctx *ctx, tanvastouch_resource_id material_id, int index, float *p_uv)
 
TANVASTOUCH_API int tanvastouch_set_material_wrapping_mode (tanvastouch_ctx *ctx, tanvastouch_resource_id material_id, int index, int mode)
 
TANVASTOUCH_API int tanvastouch_get_material_wrapping_mode (tanvastouch_ctx *ctx, tanvastouch_resource_id material_id, int index, int *p_mode)
 

Detailed Description

Macro Definition Documentation

◆ TANVASTOUCH_ERROR_MATERIAL

#define TANVASTOUCH_ERROR_MATERIAL   (7u << 16u)

Errors specific to materials.

Since
4.0.2

◆ TANVASTOUCH_ERROR_MATERIAL_INVALID_TEXTURE_INDEX

#define TANVASTOUCH_ERROR_MATERIAL_INVALID_TEXTURE_INDEX   TANVASTOUCH_AS(int, (TANVASTOUCH_ERROR_MATERIAL | 2u))

The texture index was invalid.

Version 4.0.0 of the TanvasTouch Engine supports up to three textures per material with indices 0, 1, and 2.

Since
4.0.2

◆ TANVASTOUCH_ERROR_MATERIAL_TOO_FEW_UVS

#define TANVASTOUCH_ERROR_MATERIAL_TOO_FEW_UVS   TANVASTOUCH_AS(int, (TANVASTOUCH_ERROR_MATERIAL | 1u))

There were too few elements present in the UV array passed to a set_material_uvs call. (A UV array must contain at least 8 elements.)

Since
4.0.2

Typedef Documentation

◆ tanvastouch_wrap_mode

Enumeration Type Documentation

◆ tanvastouch_wrap_mode_e

The wrapping mode for a material's texture.

Enumerator
tanvastouch_wrap_mode_clamp 

Clamps UV coordinates between 0 and 1, extending a texture's edges to the sprite's edges.

tanvastouch_wrap_mode_tile 

Tile the texture across the sprite.

Function Documentation

◆ tanvastouch_add_material_texture()

TANVASTOUCH_API int tanvastouch_add_material_texture ( tanvastouch_ctx ctx,
tanvastouch_resource_id  material_id,
int  index,
tanvastouch_resource_id  texture_id 
)

Add a texture to a material.

The default UV coordinates for a material's texture maps the full texture onto the material's sprite, i.e. they are [(0, 0), (1, 0), (1, 1), (0, 1)].

A material may currently have a maximum of 3 textures.

See also
UV coordinate storage
Parameters
ctxThe context to use.
material_idThe material to modify.
indexThe index to use; starts at zero.
texture_idThe texture to attach.
Returns
Resource-related API call return value

◆ tanvastouch_create_material()

TANVASTOUCH_API int tanvastouch_create_material ( tanvastouch_ctx ctx,
tanvastouch_resource_id p_material_id 
)

Create a material.

A material has neither an initial sprite nor texture.

The default UV coordinates for a material maps all textures onto the material's sprite, i.e. they are [(0, 0), (1, 0), (1, 1), (0, 1)].

The default wrapping mode is tanvastouch_wrap_mode_clamp.

See also
Out-parameters are only written on success
UV coordinate storage
Parameters
ctxThe context to use.
p_material_idMaterial ID storage.
Returns
Resource-related API call return value

◆ tanvastouch_destroy_material()

TANVASTOUCH_API int tanvastouch_destroy_material ( tanvastouch_ctx ctx,
tanvastouch_resource_id  material_id 
)

Destroy a material.

Destroying a material does not destroy any attached textures.

See also
Destructors do not clear resource IDs
Parameters
ctxThe context to use.
material_idThe material to destroy.
Returns
Resource-related API call return value

◆ tanvastouch_get_material_texture()

TANVASTOUCH_API int tanvastouch_get_material_texture ( tanvastouch_ctx ctx,
tanvastouch_resource_id  material_id,
int  index,
tanvastouch_resource_id p_texture_id 
)

Retrieve the texture at the given index in a material.

If there is no texture at the given index, returns TANVASTOUCH_INVALID_RESOURCE_ID.

Parameters
ctxThe context to use.
material_idThe material to query.
indexThe index in the material to query.
p_texture_idStorage for the texture ID.
Returns
Resource-related API call return value
Since
4.1.0

◆ tanvastouch_get_material_uv()

TANVASTOUCH_API int tanvastouch_get_material_uv ( tanvastouch_ctx ctx,
tanvastouch_resource_id  material_id,
int  index,
float *  p_uv 
)

Get the UV coordinates for a material's texture.

p_uv must point to storage with enough space for at least eight floats.

See also
Out-parameters are only written on success
UV coordinate storage
Parameters
ctxThe context to use.
material_idThe material to query.
indexThe texture index to query.
p_uvUV coordinate storage.
Returns
Resource-related API call return value

◆ tanvastouch_get_material_wrapping_mode()

TANVASTOUCH_API int tanvastouch_get_material_wrapping_mode ( tanvastouch_ctx ctx,
tanvastouch_resource_id  material_id,
int  index,
int *  p_mode 
)

Get the wrapping mode for a material's texture.

Parameters
ctxThe context to use.
material_idThe material to query.
indexThe texture index to query.
p_modeMode storage; see tanvastouch_wrap_mode_e for acceptable values.
Returns
Resource-related API call return value

◆ tanvastouch_remove_material_texture()

TANVASTOUCH_API int tanvastouch_remove_material_texture ( tanvastouch_ctx ctx,
tanvastouch_resource_id  material_id,
int  index 
)

Remove a texture from a material.

If a material has (say) two textures at indices 0 and 1, it is safe to remove the texture at index 0 without disturbing the texture at index 1. Removing textures does not change the indices of other textures.

Parameters
ctxThe context to use.
material_idThe material to modify.
indexThe index to remove.
Returns
Resource-related API call return value

◆ tanvastouch_set_material_uv()

TANVASTOUCH_API int tanvastouch_set_material_uv ( tanvastouch_ctx ctx,
tanvastouch_resource_id  material_id,
int  index,
float *  p_uv 
)

Set the UV coordinates of a texture in a material.

UV coordinate storage

The UV coordinates define how the texture is mapped to the material's sprite. The coordinates are supplied as an array of eight floating-point numbers which are interpreted as follows:

  [x1, y1,   x2, y2,    x3, y3,       x4, y4       ]
   top-left  top-right  bottom-right  bottom-left

The UV coordinates array must contain at least eight elements; if fewer elements are supplied, an out-of-bounds read will occur.

The default UV coordinates map the entire texture onto the sprite.

Parameters
ctxThe context to use.
material_idThe material to modify.
indexThe texture index to modify.
p_uvThe new UV coordinates.
Returns
Resource-related API call return value

◆ tanvastouch_set_material_wrapping_mode()

TANVASTOUCH_API int tanvastouch_set_material_wrapping_mode ( tanvastouch_ctx ctx,
tanvastouch_resource_id  material_id,
int  index,
int  mode 
)

Set the wrapping mode for a material's texture.

Parameters
ctxThe context to use.
material_idThe material to modify.
indexThe texture index to modify.
modeThe wrapping mode; see tanvastouch_wrap_mode_e for acceptable values.
Returns
Resource-related API call return value