- Overview
- Files
- Related Pages
- Modules

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

typedef enum tanvastouch_wrap_mode_e tanvastouch_wrap_mode

## Enumeration Type Documentation

## ◆ tanvastouch_wrap_mode_e

enum 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

  ctx | The context to use.
  material_id | The material to modify.
  index | The index to use; starts at zero.
  texture_id | The 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

  ctx | The context to use.
  p_material_id | Material 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

  ctx | The context to use.
  material_id | The 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

  ctx | The context to use.
  material_id | The material to query.
  index | The index in the material to query.
  p_texture_id | Storage 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

  ctx | The context to use.
  material_id | The material to query.
  index | The texture index to query.
  p_uv | UV 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

  ctx | The context to use.
  material_id | The material to query.
  index | The texture index to query.
  p_mode | Mode 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

  ctx | The context to use.
  material_id | The material to modify.
  index | The 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

  ctx | The context to use.
  material_id | The material to modify.
  index | The texture index to modify.
  p_uv | The 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

  ctx | The context to use.
  material_id | The material to modify.
  index | The texture index to modify.
  mode | The wrapping mode; see tanvastouch_wrap_mode_e for acceptable values.

Returns
  Resource-related API call return value