Weston

https://wayland.pages.freedesktop.org/weston/
Admin
Weston is the reference implementation of a Wayland compositor, offering a basic desktop or a...
Tokens:55,376
Snippets:603
Trust Score:7.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start seatd with sudo

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/running-weston.rst.txt

If libseat and seatd are installed but seatd is not running, it can be started with sudo. This command ensures seatd has the necessary permissions to manage seats.

```bash
sudo -- seatd -g video
```

--------------------------------

### Start My Session System Service

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/running-weston.rst.txt

Command to start the 'mysession' system service, which will prompt for a password and initiate the graphical session setup.

```bash
systemctl start mysession
```

--------------------------------

### Fixture Setup Functions

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Functions related to fixture setup arrays and running fixture setups.

```APIDOC
## fixture_setup_array_get_

### Description
Fixture data array getter method. DECLARE_FIXTURE_SETUP_WITH_ARG() overrides this in test programs. The default implementation has no data and makes the tests run once.

### Returns
const struct fixture_setup_array * - The fixture data array.

```

```APIDOC
## fixture_setup_run_

### Description
Fixture setup function. DECLARE_FIXTURE_SETUP() and DECLARE_FIXTURE_SETUP_WITH_ARG() override this in test programs. The default implementation just calls weston_test_harness_execute_standalone().

### Parameters
* **harness** (struct weston_test_harness *) - The test harness context.
* **arg_** (const void *) - The argument for the fixture setup.

### Returns
enum test_result_code - The result of the fixture setup.

```

--------------------------------

### Start My Session and Weston User Service

Source: https://wayland.pages.freedesktop.org/weston/toc/running-weston.html

These commands first start the 'mysession' system service (which may prompt for a password) and then start the Weston user service. 'loginctl' can be used to verify the active login session.

```bash
systemctl start mysession # systemd will ask for passowrd
loginctl # verify if mysession was able to perform the session login
systemctl --user start weston
```

--------------------------------

### compositor_setup_defaults_

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Initializes parts of the compositor setup structure with default values.

```APIDOC
void compositor_setup_defaults_(struct compositor_setup *setup, const char *testset_name)

Parameters:
- setup: The structure to initialize.
- testset_name: The value to set for the testset_name member.
```

--------------------------------

### Plugin Test Fixture Setup

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite.html

Fixture setup for a plugin test. This function initializes the compositor setup and executes the test as a plugin, blocking the compositor until tests are complete.

```c
static enum test_result_code
fixture_setup(struct weston_test_harness *harness)
{
     struct compositor_setup setup;

     compositor_setup_defaults(&setup);

     return weston_test_harness_execute_as_plugin(harness, &setup);
}
DECLARE_FIXTURE_SETUP(fixture_setup);


```

--------------------------------

### DECLARE_FIXTURE_SETUP_WITH_ARG

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Registers a fixture setup function that accepts a data array. The setup function is called for each element in the array, allowing tests to be repeated with different data.

```APIDOC
## DECLARE_FIXTURE_SETUP_WITH_ARG(func_, array_, meta_)

### Description
Register a fixture setup function with a data array.

### Parameters
* **func_** (function) - The function to be used as fixture setup.
* **array_** (static const array) - A static const array of arbitrary type.
* **meta_** (string) - Name of the field with type struct fixture_metadata.
```

--------------------------------

### Compositor Setup

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

The `compositor_setup` structure configures the Weston compositor, including backend, renderer, shell, and display settings.

```APIDOC
## struct compositor_setup

Weston compositor configuration. This structure determines the Weston compositor command line arguments. You should always use compositor_setup_defaults() to initialize this, then override any members you need with assignments.

### Members

- **test_quirks** (struct weston_testsuite_quirks) - The test suite quirks.
- **backend** (enum weston_compositor_backend) - The backend to use.
- **renderer** (enum weston_renderer_type) - The renderer to use.
- **shell** (enum shell_type) - The shell plugin to use.
- **xwayland** (bool) - Whether to enable xwayland support.
- **width** (unsigned) - Default output width.
- **height** (unsigned) - Default output height.
- **scale** (int) - Default output scale.
- **refresh** (int) - Default output refresh rate (headless backend); set to HIGHEST_REFRESH_RATE for maximum throughput, or to 0 for only rendering on demand (e.g. when a screenshot is requested).
- **transform** (enum wl_output_transform) - Default output transform, one of WL_OUTPUT_TRANSFORM_*.
- **config_file** (char *) - The absolute path to `weston.ini` to use, or NULL for `--no-config`. To properly fill this entry use weston_ini_setup().
- **extra_module** (const char *) - Full path to an extra plugin to load, or NULL for none.
- **logging_scopes** (const char *) - Debug scopes for the compositor log, or NULL for compositor defaults.
- **testset_name** (const char *) - The name of this test program, used as a unique identifier.
```

--------------------------------

### Start Weston User Service

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/running-weston.rst.txt

Command to start the Weston user service after logging in physically.

```bash
systemctl --user start weston
```

--------------------------------

### Weston Test Harness Fixture Setup

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite.html

Sets up the necessary environment for client tests by executing the Weston test harness as a client. This function must be called within the fixture setup for all client tests.

```c
static enum test_result_code
fixture_setup(struct weston_test_harness *harness)
{
     struct compositor_setup setup;

     compositor_setup_defaults(&setup);

     return weston_test_harness_execute_as_client(harness, &setup);
}
DECLARE_FIXTURE_SETUP(fixture_setup);
```

--------------------------------

### Start Weston Session with systemd-run

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/running-weston.rst.txt

Use systemd-run to start a Weston Wayland session. This command sets environment variables for the session type and user ID, and specifies the PAM name and TTY path. It then starts the Weston service using systemctl.

```bash
systemd-run  --collect -E XDG_SESSION_TYPE=wayland --uid=1000 -p PAMName=login -p TTYPath=/dev/tty7 sleep 1d
systemctl --user start weston
```

--------------------------------

### Client Test Fixture Setup

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/test-suite.rst.txt

Sets up the test harness to execute as a client. This is essential for client-side integration tests.

```c
static enum test_result_code
fixture_setup(struct weston_test_harness *harness)
{
	struct compositor_setup setup;

	compositor_setup_defaults(&setup);

	return weston_test_harness_execute_as_client(harness, &setup);
}
DECLARE_FIXTURE_SETUP(fixture_setup);
```

--------------------------------

### Basic Plugin Test Example

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/test-suite.rst.txt

An example of a plugin test that logs a message. Plugin tests require a fixture setup that calls weston_test_harness_execute_as_plugin and use TESTFN_PLUGIN for test cases.

```c
static enum test_result_code
log_message(struct weston_compositor *compositor)
{
	struct weston_log_client *log_client;

	log_client = weston_log_client_get(compositor);
	weston_log(log_client, "This is a plugin test log message.");

	return RESULT_OK;
}

TESTFN_PLUGIN(log_message);
```

--------------------------------

### Register Fixture Setup Function with Data Array

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Use DECLARE_FIXTURE_SETUP_WITH_ARG to register a setup function that takes a data array. The function will be called for each element in the array. The function signature must be `enum test_result_code func_(struct weston_test_harness *harness, typeof(array_[0]) *arg)`.

```c
#define DECLARE_FIXTURE_SETUP_WITH_ARG(func_, array_, meta_)

```

--------------------------------

### compositor_setup_defaults

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Initializes compositor setup to default values. These defaults include a headless backend, noop renderer, test desktop shell, disabled xwayland, specific dimensions, and on-demand repainting.

```APIDOC
## compositor_setup_defaults(s)

### Description
Initialize compositor setup to defaults.

### Parameters
* **s** (variable) - The variable to initialize.
```

--------------------------------

### Starting Weston with Debug Scopes

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/libweston/debug-flight-recorder.rst.txt

To enable flight recorder for specific scopes, start Weston with the --debug flag and specify the desired scopes. For example, to capture 'drm-backend' scope data, use '--debug -f drm-backend'.

```shell
weston --debug -f drm-backend
```

--------------------------------

### DECLARE_FIXTURE_SETUP

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Registers a fixture setup function. This function is responsible for setting up any necessary fixtures and must call one of the weston_test_harness_execute_* functions.

```APIDOC
## DECLARE_FIXTURE_SETUP(func_)

### Description
Register a fixture setup function.

### Parameters
* **func_** (function) - The function to be used as fixture setup.
```

--------------------------------

### Plugin Test Example

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite.html

An example of a plugin test that logs a message using the provided compositor pointer. Plugin tests are defined using TESTFN_PLUGIN() and receive a 'struct weston_compositor *compositor' argument.

```c
static enum test_result_code
plugin_registry_test(struct wet_testsuite_data *suite_data,
                     struct weston_compositor *compositor)
{
     testlog("Got compositor %p\n", compositor);
     return RESULT_OK;
}

DECLARE_TEST_LIST(
     TESTFN_PLUGIN(plugin_registry_test),
);


```

--------------------------------

### Fixture Metadata

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Metadata for fixture setup array elements, providing a human-friendly name for the fixture setup.

```APIDOC
## struct fixture_metadata

Metadata for fixture setup array elements.
Every type used as a fixture setup array’s elements needs one member of this type, initialized.

### Members

- **name** (const char *) - Human friendly name of the fixture setup.
```

--------------------------------

### Plugin Registry Test Example

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/test-suite.rst.txt

A basic test function that logs the compositor pointer and returns success. It's declared using DECLARE_TEST_LIST.

```c
static enum test_result_code
plugin_registry_test(struct wet_testsuite_data *suite_data,
			struct weston_compositor *compositor)
{
	testlog("Got compositor %p\n", compositor);
	return RESULT_OK;
}

DECLARE_TEST_LIST(
	TESTFN_PLUGIN(plugin_registry_test),
);
```

--------------------------------

### Plugin Test Fixture Setup

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/test-suite.rst.txt

Sets up the test harness to execute as a plugin. This is a common pattern for plugin-based tests within Weston.

```c
static enum test_result_code
fixture_setup(struct weston_test_harness *harness)
{
	struct compositor_setup setup;

	compositor_setup_defaults(&setup);

	return weston_test_harness_execute_as_plugin(harness, &setup);
}
DECLARE_FIXTURE_SETUP(fixture_setup);
```

--------------------------------

### Register Fixture Setup Function

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Use DECLARE_FIXTURE_SETUP to register a function for setting up test fixtures. The function must have the signature `enum test_result_code func_(struct weston_test_harness *harness)` and must call one of the weston_test_harness_execute_* functions.

```c
#define DECLARE_FIXTURE_SETUP(func_)

```

--------------------------------

### Process Timeline Data with wesgr

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/libweston/log.rst.txt

This example shows how to capture timeline data to a JSON file and then process it into an SVG using the wesgr tool. This is useful for diagnosing latency issues.

```console
./weston-debug timeline > log.json
./wesgr -i log.json -o log.svg
```

--------------------------------

### Standalone Test Example

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite.html

A basic standalone test that always returns success. Standalone tests do not launch the full compositor and are defined using TESTFN().

```c
static enum test_result_code
always_success(struct wet_testsuite_data *suite_data)
{
     return RESULT_OK;
}

DECLARE_TEST_LIST(
     TESTFN(always_success),
);


```

--------------------------------

### Simple Standalone Test Example

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/test-suite.rst.txt

A basic standalone test that always returns success. It demonstrates the minimal structure required for a test function and its declaration.

```c
static enum test_result_code
always_success(struct wet_testsuite_data *suite_data)
{
	return RESULT_OK;
}

DECLARE_TEST_LIST(
	TESTFN(always_success),
);
```

--------------------------------

### Configure Kiosk Shell Applications in weston.ini

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/kiosk-shell.rst.txt

Define which applications to launch on specific outputs using the 'app-ids=' field within the output section of weston.ini. This example shows how to assign applications to 'screen0'.

```ini
[output]
name=screen0
app-ids=org.domain.app1,com.domain.app2
x11-wm-name=xterm,Mozilla Firefox
x11-wm-class=Navigator
```

--------------------------------

### TESTFN_PLUGIN

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Adds a test that takes a weston_compositor argument. This macro is used within DECLARE_TEST_LIST() and is only usable when fixture setup uses weston_test_harness_execute_as_plugin().

```APIDOC
## TESTFN_PLUGIN(func)

### Description
Add a test with weston_compositor argument.

### Parameters
* **func** (function name) - The name of the function, will be also the name of the test.
```

--------------------------------

### weston_log_set_handler

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/log.html

Installs custom log and continue log functions. These functions are called by weston_log and weston_log_continue respectively to output log messages.

```APIDOC
void weston_log_set_handler(log_func_t log, log_func_t cont)

Install the log handler.
The given functions will be called to output text as passed to the _weston_log_ and _weston_log_continue_ functions.

Parameters
    
  * **log** – The log function. This function will be called when _weston_log_ is called, and should begin a new line, with user defined line headers, if any. 
  * **cont** – The continue log function. This function will be called when _weston_log_continue_ is called, and should append its output to the current line, without any header or other content in between.
```

--------------------------------

### weston_compositor_get_client

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/compositor.html

Gets the weston_client associated with a given wl_client. Each wl_client has a corresponding weston_client struct containing client tracking information.

```APIDOC
## weston_compositor_get_client

### Description
Get weston_client from wl_client. Every wl_client has an associated weston_client struct which contains client tracking information.

### Parameters
* **compositor** – The compositor instance.
* **wlclient** – The wl_client to look up, or NULL.

### Returns
If `wlclient` is NULL, returns NULL. Otherwise returns a valid pointer to the corresponding weston_client.
```

--------------------------------

### Declare Test Function with Weston Compositor Argument

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Use TESTFN_PLUGIN to add a test function that receives the weston_compositor instance as an argument. This is only usable when the fixture setup uses `weston_test_harness_execute_as_plugin()`. The function signature must be `enum test_result_code func(struct wet_testsuite_data *, struct weston_compositor *)`.

```c
#define TESTFN_PLUGIN(func)

```

--------------------------------

### Weston Systemd User Service Configuration

Source: https://wayland.pages.freedesktop.org/weston/toc/running-weston.html

This is a systemd user service file for running Weston. It specifies modules, installation targets, and execution commands. Ensure a ~/.config/weston.ini file exists for Weston to pick up configurations.

```ini
[Unit]
Description=Weston
After=systemd-user-sessions.service

[Service]
Type=simple
ExecStart=/usr/bin/weston --modules=systemd-notify.so

[Install]
WantedBy=graphical-session.target
```

--------------------------------

### weston_output_enable

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/output.html

Enables a weston_output object, making it usable by the compositor. This function calculates output coordinates, assigns an ID, sets up transformation and geometry, establishes a repaint timer, assigns a Wayland global, and calls backend-specific setup functions. It returns 0 on success and -1 on failure.

```APIDOC
## weston_output_enable

### Description
Constructs a weston_output object that can be used by the compositor. Output coordinates are calculated and each new output is by default assigned to the right of previous one. Sets up the transformation, and geometry of the output using the properties that need to be configured by the compositor. Establishes a repaint timer for the output with the relevant display object’s event loop. The output is assigned an ID (0-31). Weston can support up to 32 distinct outputs. The output is also assigned a Wayland global with the wl_output external interface. Backend specific function is called to set up the output. Output is added to the compositor’s output list. If the backend specific function fails, the weston_output object is returned to its previous state and added to the compositor’s pending_output_list. Returns 0 on success, -1 on failure.

### Parameters
* **output** (struct weston_output *) - The weston_output object that needs to be enabled. Must not be enabled already. Must have at least one head attached.

### Returns
* (int) - 0 on success, -1 on failure.
```

--------------------------------

### weston_shell_utils_view_get_layer_position

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/shell-utils.html

Gets the layer position of a view.

```APIDOC
## weston_shell_utils_view_get_layer_position

### Description
Retrieves the layer position of the specified view.

### Signature
enum weston_layer_position weston_shell_utils_view_get_layer_position(struct weston_view *view)
```

--------------------------------

### weston_output_init

Source: https://wayland.pages.freedesktop.org/weston/genindex.html

Initializes a weston_output structure.

```APIDOC
## weston_output_init

### Description
Initializes a weston_output structure.

### Method
C++ function

### Parameters
- **output** (struct weston_output *) - Pointer to the weston_output structure to initialize.
- **name** (const char *) - The name of the output.
- **x** (int) - The x-coordinate of the output's position.
- **y** (int) - The y-coordinate of the output's position.
- **width** (int) - The width of the output in pixels.
- **height** (int) - The height of the output in pixels.
- **transform** (enum wl_output_transform) - The initial transform applied to the output.
- **scale** (int) - The scale factor for the output.

### Returns
- 0 on success, -1 on failure.
```

--------------------------------

### Get Current Time

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/compositor.html

Retrieves the current system time into a timespec structure.

```c
struct timespec time;
weston_compositor_get_time(&time);
```

--------------------------------

### weston_log_scope_destroy

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/log.html

Destroys a log scope, calling each stream's destroy callback if one was installed.

```APIDOC
## weston_log_scope_destroy

### Description
Destroys a log scope, calling each stream's destroy callback if one was installed.

### Parameters
- **scope** (struct weston_log_scope *) - The log scope to destroy; may be NULL.
```

--------------------------------

### Copy Native Mode for Output

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/output.html

Sets up the native mode for an output by copying its contents. This is a workaround for fragile mode setting code and is intended to be removed later.

```c
void weston_output_copy_native_mode(struct weston_output *output, struct weston_mode *mode)
```

--------------------------------

### weston_config_next_section

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/weston-config.html

Iterates through the configuration sections. This function is used to get the next configuration section in the parsed configuration.

```APIDOC
## weston_config_next_section

### Description
Advances to the next configuration section within a `weston_config` structure.

### Signature
```c
int weston_config_next_section(struct weston_config *config, struct weston_config_section **section, const char **name)
```

### Parameters
- **config** (struct weston_config *) - Pointer to the weston_config structure.
- **section** (struct weston_config_section **) - Pointer to a pointer that will be updated to point to the next section.
- **name** (const char **) - Pointer to a pointer that will be updated to point to the name of the next section.

### Returns
- 1 if a next section was found, 0 if there are no more sections, or a negative value on error.
```

--------------------------------

### weston_output_init

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/output.html

Initializes a weston_output object, preparing it for configuration by compositors or backends. It sets initial values and uses the provided name for logging and configuration identification.

```APIDOC
## weston_output_init

### Description
Initializes a weston_output object with enough data so an output can be configured. Sets initial values for fields that are expected to be configured either by compositors or backends. The name is used in logs, and can be used by compositors as a configuration identifier.

### Parameters
* **output** (struct weston_output *) - The weston_output object to initialize.
* **compositor** (struct weston_compositor *) - The compositor instance.
* **name** (const char *) - Name for the output (the string is copied).
```

--------------------------------

### weston_output_set_ready

Source: https://wayland.pages.freedesktop.org/weston/genindex.html

Marks the output as ready.

```APIDOC
## weston_output_set_ready

### Description
Marks the output as ready.

### Method
C++ function

### Parameters
- **output** (struct weston_output *) - The output to mark as ready.
```

--------------------------------

### Configure applications for kiosk-shell

Source: https://wayland.pages.freedesktop.org/weston/toc/kiosk-shell.html

Use the `app-ids=` field in the `[output]` section of `weston.ini` to define which applications to place on specific outputs. Xwayland windows can be matched using `x11-wm-name=` or `x11-wm-class=`.

```ini
[output]
name=screen0
app-ids=org.domain.app1,com.domain.app2
x11-wm-name=xterm,Mozilla Firefox
x11-wm-class=Navigator

```

--------------------------------

### weston_log_scope_stream

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/log.html

Gets the stdio stream for a log scope, which can be used with fprintf() and similar functions. Returns NULL if the log scope is disabled.

```APIDOC
## weston_log_scope_stream

### Description
Gets the stdio stream for a log scope, which can be used with fprintf() and similar functions. Returns NULL if the log scope is disabled.

### Parameters
- **scope** (struct weston_log_scope *) - The log scope to get the stream for.

### Returns
- A FILE* stream on success, or NULL if the scope is disabled.
```

--------------------------------

### weston_compositor_create

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/compositor.html

Creates and initializes a compositor instance using the provided Wayland display, log context, user data, and optional test suite data.

```APIDOC
## weston_compositor_create

### Description
Create the compositor. This functions creates and initializes a compositor instance.

### Parameters
* **display** – The Wayland display to be used.
* **user_data** – A pointer to an object that can later be retrieved
* **log_ctx** – A pointer to weston_debug_compositor
* **test_data** – Optional testsuite data, or NULL. using the weston_compositor_get_user_data function.

### Returns
The compositor instance on success or NULL on failure.
```

--------------------------------

### execute_compositor

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Executes the compositor by manufacturing the command line and calling wet_main(). Returns RESULT_SKIP if build-disabled features are present.

```APIDOC
int execute_compositor(const struct compositor_setup *setup, struct wet_testsuite_data *data)

Returns:
- RESULT_SKIP: If the setup contains features disabled in the build (e.g., GL-renderer or DRM-backend).
```

--------------------------------

### Configure IVI-shell and Controller Modules

Source: https://wayland.pages.freedesktop.org/weston/toc/ivi-shell.html

Load the `ivi-shell.so` and a custom IVI controller module in `weston.ini` to enable the IVI-shell. Replace `hmi-controller.so` if using a custom controller.

```ini
[core]
shell=ivi-shell.so
modules=hmi-controller.so

```

--------------------------------

### fixture_setup_array Structure

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

A record for storing attributes of a data array passed to DECLARE_FIXTURE_SETUP_WITH_ARG().

```APIDOC
struct fixture_setup_array {
    const void *array;
    size_t element_size;
    int n_elements;
    size_t meta_offset;
}
```

--------------------------------

### DECLARE_TEST_LIST

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Declares the list of tests in a test program. The available macros within the argument list depend on the fixture setup method used (standalone, client, or plugin).

```APIDOC
## DECLARE_TEST_LIST(...)

### Description
Declare the list of tests in a test program.
```

--------------------------------

### Create and Destroy Compositor

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/compositor.html

Demonstrates the basic lifecycle of a weston_compositor object. Use weston_compositor_create() to initialize and weston_compositor_destroy() to release resources.

```c
struct weston_compositor *compositor;

compositor = weston_compositor_create();
// ... use compositor ...
weston_compositor_destroy(compositor);
```

--------------------------------

### Get weston_head from wl_output resource

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/head.html

Retrieves the backing weston_head object associated with a wl_output protocol resource. This is useful for accessing head-specific data from a Wayland output object.

```c
struct weston_head * weston_head_from_resource(struct wl_resource *resource)
```

--------------------------------

### weston_config_get_section

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/weston-config.html

Retrieves a specific configuration section. This function is used to get a pointer to a configuration section based on its name, and optionally filter by a key-value pair within that section.

```APIDOC
## weston_config_get_section

### Description
Retrieves a configuration section from the loaded configuration.

### Signature
```c
struct weston_config_section *weston_config_get_section(struct weston_config *config, const char *section, const char *key, const char *value)
```

### Parameters
- **config** (struct weston_config *) - Pointer to the weston_config structure.
- **section** (const char *) - The name of the configuration section to retrieve.
- **key** (const char *) - Optional key to filter the section. If NULL, any section matching the name is returned.
- **value** (const char *) - Optional value to filter the section. If NULL, any section matching the name and key is returned.

### Returns
- A pointer to the `weston_config_section` if found, otherwise NULL.
```

--------------------------------

### Weston systemd service unit

Source: https://wayland.pages.freedesktop.org/weston/toc/running-weston.html

Configure a systemd user service for Weston, ensuring it starts after its socket is ready and before the graphical session begins. It uses 'Type=notify' to signal readiness to systemd.

```ini
[Unit]
Description=Weston, a Wayland compositor, as a user service
Documentation=man:weston(1) man:weston.ini(5)
Documentation=https://wayland.freedesktop.org/

# Activate using a systemd socket
Requires=weston.socket
After=weston.socket

# Since we are part of the graphical session, make sure we are started before
Before=graphical-session.target

[Service]
Type=notify
TimeoutStartSec=60
WatchdogSec=20
# Defaults to journal
#StandardOutput=journal
StandardError=journal

```

--------------------------------

### weston_output_get_supported_eotf_modes

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/output.html

Gets a bit mask representing the supported Electro-Optical Transfer Function (EOTF) modes for an output, considering all attached heads. The result may change if heads are added or removed.

```APIDOC
## weston_output_get_supported_eotf_modes

### Description
Get supported EOTF modes as a bit mask. Returns the bit mask of the EOTF modes that all the currently attached heads claim to support. Adding or removing heads may change the result. An output can be queried regardless of whether it is enabled or disabled.
If no heads are attached, no EOTF modes are deemed supported.

### Parameters
* **output** (struct weston_output *) – The output to query.

### Returns
uint32_t – A bit mask with values from enum weston_eotf_mode or’ed together.
```

--------------------------------

### Configuration and Logging Functions

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Functions for writing configuration sections, retrieving test names and fixture indices, and logging test output.

```APIDOC
## cfg_color_profile_params

### Description
Write a color-profile section.
The image description parameters must be fully populated as defined for struct weston_color_profile_params.

### Parameters
* **name** (const char *) - Value for the ‘name’ key in the section.
* **p** (const struct weston_color_profile_params *) - Image description parameters.

### Returns
A malloc’d string containing the new config section. Usable in place of a `cfgln()` call in `weston_ini_setup()` arguments.

```

```APIDOC
## get_test_name

### Description
Get the test name string with counter. This is only usable from code paths invoked through `DECLARE_TEST_LIST()`.

### Returns
The test name with fixture number `-f%d` added. For an array driven test listed with `TESTFN_ARG()`, the name has also a `-e%d` suffix to indicate the array element number.

```

```APIDOC
## get_test_fixture_index

### Description
Get the current fixture index. Returns the current fixture index which can be used directly as an index into the array passed as an argument to DECLARE_FIXTURE_SETUP_WITH_ARG(). This is only usable from code paths invoked through `DECLARE_TEST_LIST()`.

### Returns
int - The current fixture index.

```

```APIDOC
## testlog

### Description
Print into test log. This is exactly like printf() except the output goes to the test log, which is at stderr.

### Parameters
* **fmt** (const char *) - printf format string

```

```APIDOC
## get_test_fixture_number_from_harness

### Description
Get the current fixture number from test harness. Similar to get_test_fixture_index(), but get the fixture number (index + 1) directly from the test harness. Can be called from fixture_setup() functions.

### See
DECLARE_FIXTURE_SETUP(), DECLARE_FIXTURE_SETUP_WITH_ARG()

### Parameters
* **harness** (struct weston_test_harness *) - The test harness.

### Returns
int - The current fixture number.

```

--------------------------------

### Run Weston with DRM backend and custom seat

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/running-weston.rst.txt

Launch Weston using the DRM backend and specifying the custom seat defined by udev rules. The SEATD_VTBOUND=0 environment variable indicates that no VT is associated with this seat, and LIBSEAT_BACKEND=builtin can be used to force the builtin backend if needed.

```bash
SEATD_VTBOUND=0 ./weston -Bdrm --seat=seat-insecure
```

--------------------------------

### weston_compositor_load_backend

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/compositor.html

Loads a backend into a weston_compositor, providing input/output capabilities and determining the renderer. A backend must be loaded for the compositor to function.

```APIDOC
## weston_compositor_load_backend

### Description
Loads a backend into a weston_compositor, providing input/output capabilities and determining the renderer. A backend must be loaded for the compositor to function.

### Method
struct weston_backend *

### Parameters
#### Path Parameters
- **compositor** (struct weston_compositor *) - A compositor that has not had a backend loaded yet.
- **backend** (enum weston_compositor_backend) - Name of the backend file.
- **config_base** (struct weston_backend_config *) - A pointer to a backend-specific configuration structure’s ‘base’ member.

### Returns
A new `weston_backend` on success, or NULL on error.
```

--------------------------------

### Verify Session Login

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/running-weston.rst.txt

Command to check the status of systemd logins and verify if 'mysession' successfully established a login session.

```bash
loginctl
```

--------------------------------

### weston_output_set_ready

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/output.html

Informs the compositor that an output is ready for its first repaint, preventing potential startup issues with uninitialized buffers. This should be called once per output when content is available.

```APIDOC
## weston_output_set_ready

### Description
Inform the compositor that an output is ready for its first repaint. When a new output is added, it may not have any content to be displayed. This could lead to strange flickers or hangs at startup if uninitialized buffers become attached for scanout. To prevent this, we assert that the output has content to display.
The shell must inform the compositor when content such as a background is in the scene graph and this output can safely be repainted.
Only needs to be called once per output, and an output can never become unready.

### Parameters
* **output** (struct weston_output *) – the output that has become ready
```

--------------------------------

### Switch Output Mode to Native

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/output.html

Switches the current mode of a `weston_output` to its native mode.

```c
int weston_output_mode_switch_to_native(struct weston_output *output)
```

--------------------------------

### Wake Compositor

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/compositor.html

Restores the compositor to active status. Powers on outputs and fires the wake signal if the compositor was inactive. Restarts the idle timer.

```c
weston_compositor_wake(compositor);
```

--------------------------------

### weston_output_copy_native_mode

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/output.html

Sets up the native mode for an output by copying its contents. This is a workaround for fragile mode setting code and is intended to be removed in the future.

```APIDOC
## weston_output_copy_native_mode

### Description
Set up the native mode for an output.
Our mode setting code does some ugly tricks, and will sometimes save pointers to ephemeral structures for comparison later.
To work around this fragility, we copy the contents of the native mode at set time.
This function will be removed when we fix the mode set code.

### Parameters
* **output** (struct weston_output *) - The weston_output object
* **mode** (struct weston_mode *) - The new native mode
```

--------------------------------

### weston_compositor_load_color_manager

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/compositor.html

Loads the Little CMS color manager plugin. Calling this before loading any backend sets Little CMS as the active color matching module.

```APIDOC
## weston_compositor_load_color_manager

### Description
Loads the Little CMS color manager plugin. Calling this before loading any backend sets Little CMS as the active color matching module.

### Method
int

### Parameters
#### Path Parameters
- **compositor** (struct weston_compositor *) - Description not provided.
```

--------------------------------

### weston_compositor_load_xwayland

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/compositor.html

Loads the Xwayland component for the compositor.

```APIDOC
## weston_compositor_load_xwayland

### Description
Loads the Xwayland component for the compositor.

### Method
int

### Parameters
#### Path Parameters
- **compositor** (struct weston_compositor *) - Description not provided.
```

--------------------------------

### weston_head_init

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/head.html

Initializes a pre-allocated weston_head object, making it safe for use.

```APIDOC
## weston_head_init

### Description
Initialize a pre-allocated weston_head. The head will be safe to attach, detach and release. The name is used in logs, and can be used by compositors as a configuration identifier.

### Parameters
- **head** (struct weston_head *) - The head to initialize.
- **name** (const char *) - The head name, e.g. the connector name or equivalent.
```

--------------------------------

### weston_output_mode_switch_to_native

Source: https://wayland.pages.freedesktop.org/weston/genindex.html

Switches the output to its native mode.

```APIDOC
## weston_output_mode_switch_to_native

### Description
Switches the output to its native mode.

### Method
C++ function

### Parameters
- **output** (struct weston_output *) - The output to switch to its native mode.
```

--------------------------------

### Create udev rule for a new seat

Source: https://wayland.pages.freedesktop.org/weston/toc/running-weston.html

Create a udev file to assign specific hardware devices to a new seat, preventing them from being used by the primary display environment. Follow the naming scheme for udev rules and check for potential precedence issues with existing rules.

```udev
ACTION=="remove", GOTO="id_insecure_seat_end"

SUBSYSTEM=="drm", KERNEL=="card*", KERNELS=="0000:00:02.0", ENV{ID_SEAT}="seat-insecure"

SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004d", OWNER="your_user_id", ENV{ID_SEAT}="seat-insecure", ENV{WL_OUTPUT}="HDMI-A-1"
SUBSYSTEM=="input", ATTRS{idVendor}=="03f0", ATTRS{idProduct}=="1198", OWNER="your_user_id", ENV{ID_SEAT}="seat-insecure"

LABEL="id_insecure_seat_end"

```

--------------------------------

### weston_test_harness_execute_as_client

Source: https://wayland.pages.freedesktop.org/weston/genindex.html

Executes a test case as a client process.

```APIDOC
## weston_test_harness_execute_as_client

### Description
Executes a test case as a client process.

### Method
C++ function

### Parameters
- **test_name** (const char *) - The name of the test case to execute.
- **args** (char **) - Array of arguments for the test case.
- **num_args** (int) - The number of arguments.

### Returns
- 0 on success, non-zero on failure.
```

--------------------------------

### wet_test_post_sem

Source: https://wayland.pages.freedesktop.org/weston/toc/test-suite-api.html

Safely handles posting a semaphore to wake a waiting thread.

```APIDOC
static inline void wet_test_post_sem(sem_t *sem)
```

--------------------------------

### Enable a Weston Output

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/output.html

Enables a `weston_output` object for use by the compositor. The output must not be already enabled.

```c
weston_output_enable(output);
```

--------------------------------

### weston_compositor_wake

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/compositor.html

Restores the compositor to active status, powering on outputs and firing the wake signal.

```APIDOC
## weston_compositor_wake

### Description
Restores the compositor to active status. If the compositor was in a sleeping mode, all outputs are powered back on via DPMS. Otherwise if the compositor was inactive (idle/locked, offscreen, or sleeping) then the compositor’s wake signal will fire. Restarts the idle timer.

### Parameters
* **compositor** (struct weston_compositor *) - The compositor instance.
```

--------------------------------

### weston_shell_utils_curtain_create

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/shell-utils.html

Creates a new curtain object.

```APIDOC
## weston_shell_utils_curtain_create

### Description
Creates a new curtain object associated with the compositor.

### Signature
struct weston_curtain *weston_shell_utils_curtain_create(struct weston_compositor *compositor, struct weston_curtain_params *params)
```

--------------------------------

### GDB Batch Script for Flight Recorder

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/libweston/debug-flight-recorder.rst.txt

Create a GDB batch script to automate the process of loading the flight recorder Python script and displaying the recorded data. Ensure the path to 'flight_rec.py' is correctly set.

```gdb
source /path/to/flight_rec.py
display_flight_rec
```

--------------------------------

### weston_compositor_get_touch_devices

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/compositor.html

Retrieves a list of all touch devices connected to the compositor. The pointers in the returned list are valid until a touch device is destroyed.

```APIDOC
## weston_compositor_get_touch_devices

### Description
Retrieves a list of all touch devices connected to the compositor. The pointers in the returned list are valid until a touch device is destroyed.

### Method
struct weston_touch_device_list

### Parameters
#### Path Parameters
- **compositor** (struct weston_compositor *) - The compositor instance.

### Returns
A list of touch devices.
```

--------------------------------

### Roundtrip Test

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/test-suite.rst.txt

A simple test that creates a client and performs a roundtrip to ensure basic communication works.

```c
static enum test_result_code
test_roundtrip(struct wet_testsuite_data *suite_data)
{
	struct client *client;

	client = create_client_and_test_surface(100, 50, 123, 77);
	client_roundtrip(client);
	return RESULT_OK;
}
```

--------------------------------

### Run Weston on a specific seat

Source: https://wayland.pages.freedesktop.org/weston/toc/running-weston.html

Launch Weston using the DRM-backend and specifying the custom seat created via udev rules. This command assumes the use of the libseat launcher with the 'builtin' backend.

```bash
SEATD_VTBOUND=0 ./weston -Bdrm --seat=seat-insecure

```

--------------------------------

### weston_output_get_supported_eotf_modes

Source: https://wayland.pages.freedesktop.org/weston/genindex.html

Retrieves a list of supported EOTF modes for the output.

```APIDOC
## weston_output_get_supported_eotf_modes

### Description
Retrieves a list of supported EOTF modes for the output.

### Method
C++ function

### Parameters
- **output** (struct weston_output *) - The output to query.

### Returns
- A pointer to a null-terminated array of integers representing the supported EOTF modes.
```

--------------------------------

### Enable weston-debug Protocol

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/log.html

Enable the weston-debug protocol extension in the libweston compositor. This allows clients to subscribe to debug messages. Warning: This feature should not be used in production due to potential blocking issues.

```c
void weston_compositor_enable_debug_protocol(struct weston_compositor *compositor)
```

--------------------------------

### weston_compositor_create

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/libweston/compositor.rst.txt

Creates a new Westion compositor object. This function initializes the core object and its associated state, preparing it to manage Wayland surfaces and clients.

```APIDOC
## weston_compositor_create

### Description
Creates a new Westion compositor object.

### Parameters
None explicitly documented in this section.

### Returns
- weston_compositor* - A pointer to the newly created compositor object, or NULL on failure.
```

--------------------------------

### weston_output_enable

Source: https://wayland.pages.freedesktop.org/weston/genindex.html

Enables an output.

```APIDOC
## weston_output_enable

### Description
Enables an output.

### Method
C++ function

### Parameters
- **output** (struct weston_output *) - The output to enable.
```

--------------------------------

### weston_output_mode_switch_to_temporary

Source: https://wayland.pages.freedesktop.org/weston/genindex.html

Switches the output to a temporary mode.

```APIDOC
## weston_output_mode_switch_to_temporary

### Description
Switches the output to a temporary mode.

### Method
C++ function

### Parameters
- **output** (struct weston_output *) - The output to switch to a temporary mode.
- **mode** (struct weston_mode *) - Pointer to the temporary mode structure.
```

--------------------------------

### Switch Output Mode to Temporary

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/output.html

Switches the current mode of a `weston_output` to a temporary mode with a specified scale.

```c
int weston_output_mode_switch_to_temporary(struct weston_output *output, struct weston_mode *mode, int32_t scale)
```

--------------------------------

### Configure IVI-shell and Controller Module

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/ivi-shell.rst.txt

This configuration is required in weston.ini to enable the IVI-shell and its associated controller module. Replace 'hmi-controller.so' if using a custom controller.

```ini
[core]
shell=ivi-shell.so
modules=hmi-controller.so
```

--------------------------------

### weston_compositor_create_output

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/compositor.html

Creates a new named output for an unused head, attaching the specified head to it. The output must be configured with at least one head before it can be enabled.

```APIDOC
## weston_compositor_create_output

### Description
Create a named output for an unused head. This creates a new weston_output that starts with the given head attached. The head must not be already attached to another output. An output must be configured and it must have at least one head before it can be enabled.

### Parameters
* **compositor** – The compositor.
* **head** – The head to attach to the output.
* **name** – The name for the output.

### Returns
A new `weston_output`, or NULL on failure.
```

--------------------------------

### Udev rules for a custom seat

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/running-weston.rst.txt

Create a udev file to assign specific hardware, like a DRM device and input devices, to a custom seat named 'seat-insecure'. This allows Weston to use dedicated hardware without interfering with the primary display environment.

```udev
ACTION=="remove", GOTO="id_insecure_seat_end"

SUBSYSTEM=="drm", KERNEL=="card*", KERNELS=="0000:00:02.0", ENV{ID_SEAT}="seat-insecure"

SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004d", OWNER="your_user_id", ENV{ID_SEAT}="seat-insecure", ENV{WL_OUTPUT}="HDMI-A-1"
SUBSYSTEM=="input", ATTRS{idVendor}=="03f0", ATTRS{idProduct}=="1198", OWNER="your_user_id", ENV{ID_SEAT}="seat-insecure"

LABEL="id_insecure_seat_end"
```

--------------------------------

### Pick View at Position

Source: https://wayland.pages.freedesktop.org/weston/toc/libweston/compositor.html

Identifies the weston_view object at a given global coordinate.

```c
struct weston_view *view;
struct weston_coord_global pos = { x, y };
view = weston_compositor_pick_view(compositor, pos);
```

--------------------------------

### weston_test_harness_execute_as_plugin

Source: https://wayland.pages.freedesktop.org/weston/genindex.html

Executes a test case as a plugin.

```APIDOC
## weston_test_harness_execute_as_plugin

### Description
Executes a test case as a plugin.

### Method
C++ function

### Parameters
- **test_name** (const char *) - The name of the test case to execute.
- **args** (char **) - Array of arguments for the test case.
- **num_args** (int) - The number of arguments.

### Returns
- 0 on success, non-zero on failure.
```

--------------------------------

### weston_output_schedule_repaint

Source: https://wayland.pages.freedesktop.org/weston/genindex.html

Schedules a repaint for the output.

```APIDOC
## weston_output_schedule_repaint

### Description
Schedules a repaint for the output.

### Method
C++ function

### Parameters
- **output** (struct weston_output *) - The output to schedule a repaint for.
- **rect** (const struct weston_rect *) - The region to repaint. If NULL, the entire output is repainted.
```

--------------------------------

### Client Test List Declaration

Source: https://wayland.pages.freedesktop.org/weston/_sources/toc/test-suite.rst.txt

Declares the test functions for client tests, including one that takes arguments and another simple roundtrip test.

```c
DECLARE_TEST_LIST(
	TESTFN_ARG(test_viewporter_bad_source_rect, bad_source_rect_args),
	TESTFN(test_roundtrip),
);
```
Tokens:
Raw