# lv_gltf.h (/api/public/widgets/lv_gltf_h)
Functions [#functions]
lv_gltf_set_environment [#lv_gltf_set_environment]
Assign an environment to a glTF object for IBL rendering
```c title=" " lineNumbers=1
void lv_gltf_set_environment(lv_obj_t *obj, lv_gltf_environment_t *environment)
```
Parameters
| Name | Type | Description |
| ------------- | -------------------------------------------------------------------------- | --------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `environment` | | pointer to the environment to use |
The environment can be shared across multiple glTF objects
If no environment is set before attempting to load a file, a default one will be created for you
lv_gltf_set_yaw [#lv_gltf_set_yaw]
Set the yaw (horizontal rotation) of the camera
```c title=" " lineNumbers=1
void lv_gltf_set_yaw(lv_obj_t *obj, float yaw)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `yaw` | `float` | yaw angle in degrees |
lv_gltf_set_pitch [#lv_gltf_set_pitch]
Set the pitch (vertical rotation) of the camera
```c title=" " lineNumbers=1
void lv_gltf_set_pitch(lv_obj_t *obj, float pitch)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `pitch` | `float` | pitch angle in degrees |
lv_gltf_set_distance [#lv_gltf_set_distance]
Set the camera distance from the focal point
```c title=" " lineNumbers=1
void lv_gltf_set_distance(lv_obj_t *obj, float value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `value` | `float` | distance value |
lv_gltf_set_fov [#lv_gltf_set_fov]
Set the field of view
```c title=" " lineNumbers=1
void lv_gltf_set_fov(lv_obj_t *obj, float value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `value` | `float` | vertical FOV in degrees. If zero, the view will be orthographic (non-perspective) |
lv_gltf_set_focal_x [#lv_gltf_set_focal_x]
Set the X coordinate of the camera focal point
```c title=" " lineNumbers=1
void lv_gltf_set_focal_x(lv_obj_t *obj, float value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `value` | `float` | X coordinate |
lv_gltf_set_focal_y [#lv_gltf_set_focal_y]
Set the Y coordinate of the camera focal point
```c title=" " lineNumbers=1
void lv_gltf_set_focal_y(lv_obj_t *obj, float value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `value` | `float` | Y coordinate |
lv_gltf_set_focal_z [#lv_gltf_set_focal_z]
Set the Z coordinate of the camera focal point
```c title=" " lineNumbers=1
void lv_gltf_set_focal_z(lv_obj_t *obj, float value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `value` | `float` | Z coordinate |
lv_gltf_set_camera [#lv_gltf_set_camera]
Set the active camera index The camera is selected from the first glTF model added to the viewer
```c title=" " lineNumbers=1
void lv_gltf_set_camera(lv_obj_t *obj, uint32_t value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | -------------------------------------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `value` | `uint32_t` | camera index (0 for default camera, 1+ for scene camera index) |
Values higher than the scene's camera count will be clamped to the maximum available camera index
lv_gltf_set_animation_speed [#lv_gltf_set_animation_speed]
DEPRECATED. See `lv_gltf_model_set_animation_speed`
Set the animation speed ratio
The actual ratio is the value parameter / LV\_GLTF\_ANIM\_SPEED\_NORMAL Values greater than LV\_GLTF\_ANIM\_SPEED\_NORMAL will speed-up the animation Values less than LV\_GLTF\_ANIM\_SPEED\_NORMAL will slow down the animation
```c title=" " lineNumbers=1
void lv_gltf_set_animation_speed(lv_obj_t *obj, uint32_t value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `value` | `uint32_t` | speed-up ratio of the animation |
lv_gltf_set_background_mode [#lv_gltf_set_background_mode]
Set the background mode
```c title=" " lineNumbers=1
void lv_gltf_set_background_mode(lv_obj_t *obj, lv_gltf_bg_mode_t value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `value` | | background mode |
lv_gltf_set_background_blur [#lv_gltf_set_background_blur]
Set the background blur amount
```c title=" " lineNumbers=1
void lv_gltf_set_background_blur(lv_obj_t *obj, uint32_t value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `value` | `uint32_t` | blur amount between 0 and 100 |
lv_gltf_set_environment_brightness [#lv_gltf_set_environment_brightness]
Set the environment brightness of a glTF viewer.
```c title=" " lineNumbers=1
void lv_gltf_set_environment_brightness(lv_obj_t *obj, float value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | -------------------------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `value` | `float` | brightness multiplier, 1.0 = neutral. Default: 1.8 |
lv_gltf_set_env_brightness [#lv_gltf_set_env_brightness]
Set the environment brightness.
\> **Deprecated:** Use instead, which takes a multiplier (1.0 = neutral).
```c title=" " lineNumbers=1
void lv_gltf_set_env_brightness(lv_obj_t *obj, uint32_t value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------------ |
| `obj` | | pointer to a glTF viewer object |
| `value` | `uint32_t` | brightness percentage, 100 = neutral |
lv_gltf_set_image_exposure [#lv_gltf_set_image_exposure]
Set the image exposure level
```c title=" " lineNumbers=1
void lv_gltf_set_image_exposure(lv_obj_t *obj, float value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `value` | `float` | exposure level (1.0 is default) |
lv_gltf_set_antialiasing_mode [#lv_gltf_set_antialiasing_mode]
Set the anti-aliasing mode
```c title=" " lineNumbers=1
void lv_gltf_set_antialiasing_mode(lv_obj_t *obj, lv_gltf_aa_mode_t value)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `value` | | anti-aliasing mode |
lv_gltf_get_model_count [#lv_gltf_get_model_count]
Get the number of models loaded in the glTF viewer
```c title=" " lineNumbers=1
size_t lv_gltf_get_model_count(lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `size_t` — the total number of models in the viewer
lv_gltf_get_model_by_index [#lv_gltf_get_model_by_index]
Get a specific model by its index
```c title=" " lineNumbers=1
lv_gltf_model_t * lv_gltf_get_model_by_index(const lv_obj_t *obj, size_t id)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ---------------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `id` | `size_t` | index of the model to retrieve (0-based) |
**Returns:** — pointer to the model at the specified index, or NULL if index is invalid
lv_gltf_get_primary_model [#lv_gltf_get_primary_model]
Get the primary model from the glTF viewer The primary model is the first model added to the viewer and can be used for camera selection and other primary operations
```c title=" " lineNumbers=1
lv_gltf_model_t * lv_gltf_get_primary_model(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** — pointer to the primary model, or NULL if no models are loaded
lv_gltf_get_yaw [#lv_gltf_get_yaw]
Get the yaw (horizontal rotation) of the camera
```c title=" " lineNumbers=1
float lv_gltf_get_yaw(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `float` — yaw angle in degrees
lv_gltf_get_pitch [#lv_gltf_get_pitch]
Get the pitch (vertical rotation) of the camera
```c title=" " lineNumbers=1
float lv_gltf_get_pitch(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `float` — pitch angle in degrees
lv_gltf_get_distance [#lv_gltf_get_distance]
Get the camera distance scale factor from the focal point
```c title=" " lineNumbers=1
float lv_gltf_get_distance(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `float` — distance scaling factor value
lv_gltf_get_world_distance [#lv_gltf_get_world_distance]
Get the camera distance from the focal point in world units
```c title=" " lineNumbers=1
float lv_gltf_get_world_distance(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a GLTF viewer object |
**Returns:** `float` — world unit distance value
lv_gltf_get_fov [#lv_gltf_get_fov]
Get the field of view
```c title=" " lineNumbers=1
float lv_gltf_get_fov(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `float` — vertical FOV in degrees
lv_gltf_get_focal_x [#lv_gltf_get_focal_x]
Get the X coordinate of the camera focal point
```c title=" " lineNumbers=1
float lv_gltf_get_focal_x(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `float` — X coordinate
lv_gltf_get_focal_y [#lv_gltf_get_focal_y]
Get the Y coordinate of the camera focal point
```c title=" " lineNumbers=1
float lv_gltf_get_focal_y(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `float` — Y coordinate
lv_gltf_get_focal_z [#lv_gltf_get_focal_z]
Get the Z coordinate of the camera focal point
```c title=" " lineNumbers=1
float lv_gltf_get_focal_z(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `float` — Z coordinate
lv_gltf_get_camera [#lv_gltf_get_camera]
Get the active camera index
```c title=" " lineNumbers=1
uint32_t lv_gltf_get_camera(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `uint32_t` — active camera index
lv_gltf_get_camera_count [#lv_gltf_get_camera_count]
Get the number of cameras in the first glTF model added to the viewer This count represents the valid range for the camera index parameter used with
To get the camera count of other models, call lv\_gltf\_model\_get\_camera\_count(model) directly with the specific model
```c title=" " lineNumbers=1
uint32_t lv_gltf_get_camera_count(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `uint32_t` — number of available cameras
lv_gltf_get_animation_speed [#lv_gltf_get_animation_speed]
DEPRECATED. See `lv_gltf_model_get_animation_speed`
Get the animation speed ratio
The actual ratio is the return value / LV\_GLTF\_ANIM\_SPEED\_NORMAL
```c title=" " lineNumbers=1
uint32_t lv_gltf_get_animation_speed(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
lv_gltf_get_background_mode [#lv_gltf_get_background_mode]
Get the background mode
```c title=" " lineNumbers=1
lv_gltf_bg_mode_t lv_gltf_get_background_mode(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** — background mode
lv_gltf_get_background_blur [#lv_gltf_get_background_blur]
Get the background blur amount
```c title=" " lineNumbers=1
uint32_t lv_gltf_get_background_blur(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `uint32_t` — blur amount between 0 and 100
lv_gltf_get_environment_brightness [#lv_gltf_get_environment_brightness]
Get the environment brightness of a glTF viewer.
```c title=" " lineNumbers=1
float lv_gltf_get_environment_brightness(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `float` — brightness multiplier, 1.0 = neutral
lv_gltf_get_env_brightness [#lv_gltf_get_env_brightness]
Get the environment brightness.
\> **Deprecated:** Use instead, which returns a multiplier (1.0 = neutral).
```c title=" " lineNumbers=1
uint32_t lv_gltf_get_env_brightness(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `uint32_t` — brightness percentage, 100 = neutral
lv_gltf_get_image_exposure [#lv_gltf_get_image_exposure]
Get the image exposure level
```c title=" " lineNumbers=1
float lv_gltf_get_image_exposure(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** `float` — exposure level
lv_gltf_get_antialiasing_mode [#lv_gltf_get_antialiasing_mode]
Get the anti-aliasing mode
```c title=" " lineNumbers=1
lv_gltf_aa_mode_t lv_gltf_get_antialiasing_mode(const lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
**Returns:** — anti-aliasing mode
lv_gltf_get_current_view_plane [#lv_gltf_get_current_view_plane]
Get a plane that faces the current view camera, centered some units in front of it
```c title=" " lineNumbers=1
lv_3dplane_t lv_gltf_get_current_view_plane(lv_obj_t *obj, float distance)
```
Parameters
| Name | Type | Description |
| ---------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `obj` | | pointer to a GLTF viewer object |
| `distance` | `float` | distance in front of the camera to set the plane, in world units. see lv\_gltf\_get\_world\_distance to get the auto-distance |
**Returns:** — camera facing plane
lv_gltf_get_ray_from_2d_coordinate [#lv_gltf_get_ray_from_2d_coordinate]
Calculates a ray originating from the camera and passing through the specified mouse position on the screen.
```c title=" " lineNumbers=1
lv_3dray_t lv_gltf_get_ray_from_2d_coordinate(lv_obj_t *obj, const lv_point_t *screen_pos)
```
Parameters
| Name | Type | Description |
| ------------ | ---------------------------------------------------------- | ------------------------------- |
| `obj` | | pointer to a GLTF viewer object |
| `screen_pos` | | screen coordinate, in pixels |
**Returns:** — mouse point ray
lv_gltf_create [#lv_gltf_create]
Create a glTF object
```c title=" " lineNumbers=1
lv_obj_t * lv_gltf_create(lv_obj_t *parent)
```
Parameters
| Name | Type | Description |
| -------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `parent` | | pointer to a parent widget **May** be `NULL`.. When NULL, the widget is created as a screen on the default display. |
**Returns:** — pointer to the created glTF object
lv_gltf_load_model_from_file [#lv_gltf_load_model_from_file]
Load a glTF model from a file into the viewer
```c title=" " lineNumbers=1
lv_gltf_model_t * lv_gltf_load_model_from_file(lv_obj_t *obj, const char *path)
```
Parameters
| Name | Type | Description |
| ------ | ------------------------------------------------ | ----------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `path` | `const char *` | file path to the glTF model to load |
**Returns:** — pointer to the loaded glTF model, or NULL on failure
lv_gltf_load_model_from_bytes [#lv_gltf_load_model_from_bytes]
Load a glTF model from a byte array into the viewer
```c title=" " lineNumbers=1
lv_gltf_model_t * lv_gltf_load_model_from_bytes(lv_obj_t *obj, const uint8_t *bytes, size_t len)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `bytes` | `const uint8_t *` | glTF raw data |
| `len` | `size_t` | glTF raw data length in bytes |
**Returns:** — pointer to the loaded glTF model, or NULL on failure
lv_gltf_add_model [#lv_gltf_add_model]
Add a glTF model to the viewer.
Contrary to `lv_gltf_load_model_from_file` and `lv_gltf_load_model_from_bytes`, the model is owned by the caller of this function meaning that it's the caller's responsibility to delete the model when it is no longer needed, with `lv_gltf_model_delete`. Deleting it while the viewer still shows it is allowed, the viewer lets go of it.
```c title=" " lineNumbers=1
lv_result_t lv_gltf_add_model(lv_obj_t *obj, lv_gltf_model_t *model)
```
Parameters
| Name | Type | Description |
| ------- | -------------------------------------------------------------- | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `model` | | glTF model to add to the viewer |
**Returns:** — LV\_RESULT\_OK if the model was added to the viewer or LV\_RESULT\_INVALID on failure
lv_gltf_remove_model [#lv_gltf_remove_model]
Remove a model from the glTF viewer
```c title=" " lineNumbers=1
void lv_gltf_remove_model(lv_obj_t *obj, lv_gltf_model_t *model)
```
Parameters
| Name | Type | Description |
| ------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `model` | | model to remove. Nothing happens if the viewer doesn't hold it |
lv_gltf_remove_all_models [#lv_gltf_remove_all_models]
Remove all models from the glTF viewer
```c title=" " lineNumbers=1
void lv_gltf_remove_all_models(lv_obj_t *obj)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------ | ------------------------------- |
| `obj` | | pointer to a glTF viewer object |
lv_gltf_recenter [#lv_gltf_recenter]
Set the focal coordinates to the center point of the model object
```c title=" " lineNumbers=1
void lv_gltf_recenter(lv_obj_t *obj, lv_gltf_model_t *model)
```
Parameters
| Name | Type | Description |
| ------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `obj` | | pointer to a glTF viewer object |
| `model` | | a model attached to this viewer. **May** be `NULL`. Pass NULL to use the primary model |
lv_intersect_ray_with_plane [#lv_intersect_ray_with_plane]
Get the point that a given ray intersects with a specified plane at, if any
```c title=" " lineNumbers=1
lv_result_t lv_intersect_ray_with_plane(const lv_3dray_t *ray, const lv_3dplane_t *plane, lv_3dpoint_t *collision_point)
```
Parameters
| Name | Type | Description |
| ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `ray` | | the intersection test ray |
| `plane` | | the plane to test ray intersection with |
| `collision_point` | | output holder, values are only valid if true is the return value |
**Returns:** — LV\_RESULT\_OK if intersection, LV\_RESULT\_INVALID if no intersection
lv_gltf_world_to_screen [#lv_gltf_world_to_screen]
Get the screen position of a 3d point
```c title=" " lineNumbers=1
lv_result_t lv_gltf_world_to_screen(lv_obj_t *obj, const lv_3dpoint_t world_pos, lv_point_t *screen_pos)
```
Parameters
| Name | Type | Description |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------------ |
| `obj` | | pointer to a GLTF viewer object |
| `world_pos` | | world position to convert |
| `screen_pos` | | the resulting point, in pixels. only valid if return value is true |
**Returns:** — LV\_RESULT\_OK if conversion valid, LV\_RESULT\_INVALID if no valid conversion
Enums [#enums]
lv_gltf_aa_mode_t [#lv_gltf_aa_mode_t]
| Name | Value | Description |
| ------------------------- | ----- | ----------------- |
| `LV_GLTF_AA_MODE_OFF` | `0` | |
| `LV_GLTF_AA_MODE_ON` | `1` | Anti aliasing off |
| `LV_GLTF_AA_MODE_DYNAMIC` | `2` | Anti aliasing on |
* `lv_gltf_set_antialiasing_mode` — param `value`
lv_gltf_bg_mode_t [#lv_gltf_bg_mode_t]
| Name | Value | Description |
| ----------------------------- | ----- | ----------------------------------------------------------------------------- |
| `LV_GLTF_BG_MODE_SOLID` | `0` | |
| `LV_GLTF_BG_MODE_ENVIRONMENT` | `1` | Solid background. Use `lv_obj_set_style_bg_color` to set the background color |
* `lv_gltf_set_background_mode` — param `value`
Dependencies [#dependencies]