"Fossies" - the Fresh Open Source Software Archive

Member "mesa-20.1.8/src/gallium/docs/source/screen.rst" (16 Sep 2020, 55787 Bytes) of package /linux/misc/mesa-20.1.8.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "screen.rst": 20.1.5_vs_20.2.0-rc1.

Screen

A screen is an object representing the context-independent part of a device.

Flags and enumerations

XXX some of these don't belong in this section.

PIPE_CAP*

Capability queries return information about the features and limits of the driver/GPU. For floating-point values, use get_paramf, and for boolean or integer values, use get_param.

The integer capabilities:

PIPE_CAPF*

The floating-point capabilities are:

PIPE_SHADER_CAP*

These are per-shader-stage capabitity queries. Different shader stages may support different features.

If a value greater than 0 is returned, the driver can have multiple constant buffers bound to shader stages. The CONST register file is accessed with two-dimensional indices, like in the example below.

DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0 DCL CONST[3][0] # declare first vector of constbuf 3 MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0

PIPE_COMPUTE_CAP*

Compute-specific capabilities. They can be queried using pipe_screen::get_compute_param.

PIPE_BIND*

These flags indicate how a resource will be used and are specified at resource creation time. Resources may be used in different roles during their lifecycle. Bind flags are cumulative and may be combined to create a resource which can be used for multiple things. Depending on the pipe driver's memory management and these bind flags, resources might be created and handled quite differently.

PIPE_USAGE*

The PIPE_USAGE enums are hints about the expected usage pattern of a resource. Note that drivers must always support read and write CPU access at any time no matter which hint they got.

Methods

XXX to-do

get_name

Returns an identifying name for the screen.

The returned string should remain valid and immutable for the lifetime of pipe_screen.

get_vendor

Returns the screen vendor.

The returned string should remain valid and immutable for the lifetime of pipe_screen.

get_device_vendor

Returns the actual vendor of the device driving the screen (as opposed to the driver vendor).

The returned string should remain valid and immutable for the lifetime of pipe_screen.

get_param

Get an integer/boolean screen parameter.

param is one of the PIPE_CAP names.

get_paramf

Get a floating-point screen parameter.

param is one of the PIPE_CAPF names.

context_create

Create a pipe_context.

priv is private data of the caller, which may be put to various unspecified uses, typically to do with implementing swapbuffers and/or front-buffer rendering.

is_format_supported

Determine if a resource in the given format can be used in a specific manner.

format the resource format

target one of the PIPE_TEXTURE_x flags

sample_count the number of samples. 0 and 1 mean no multisampling, the maximum allowed legal value is 32.

storage_sample_count the number of storage samples. This must be <= sample_count. See the documentation of pipe_resource::nr_storage_samples.

bindings is a bitmask of PIPE_BIND flags.

Returns TRUE if all usages can be satisfied.

can_create_resource

Check if a resource can actually be created (but don't actually allocate any memory). This is used to implement OpenGL's proxy textures. Typically, a driver will simply check if the total size of the given resource is less than some limit.

For PIPE_TEXTURE_CUBE, the pipe_resource::array_size field should be 6.

resource_create

Create a new resource from a template. The following fields of the pipe_resource must be specified in the template:

target one of the pipe_texture_target enums. Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different. Modern APIs allow using buffers as shader resources.

format one of the pipe_format enums.

width0 the width of the base mip level of the texture or size of the buffer.

height0 the height of the base mip level of the texture (1 for 1D or 1D array textures).

depth0 the depth of the base mip level of the texture (1 for everything else).

array_size the array size for 1D and 2D array textures. For cube maps this must be 6, for other textures 1.

last_level the last mip map level present.

nr_samples: Number of samples determining quality, driving the rasterizer, shading, and framebuffer. It is the number of samples seen by the whole graphics pipeline. 0 and 1 specify a resource which isn't multisampled.

nr_storage_samples: Only color buffers can set this lower than nr_samples. Multiple samples within a pixel can have the same color. nr_storage_samples determines how many slots for different colors there are per pixel. If there are not enough slots to store all sample colors, some samples will have an undefined color (called "undefined samples").

The resolve blit behavior is driver-specific, but can be one of these two:

  1. Only defined samples will be averaged. Undefined samples will be ignored.
  2. Undefined samples will be approximated by looking at surrounding defined samples (even in different pixels).

Blits and MSAA texturing: If the sample being fetched is undefined, one of the defined samples is returned instead.

Sample shading (set_min_samples) will operate at a sample frequency that is at most nr_storage_samples. Greater min_samples values will be replaced by nr_storage_samples.

usage one of the PIPE_USAGE flags.

bind bitmask of the PIPE_BIND flags.

flags bitmask of PIPE_RESOURCE_FLAG flags.

next: Pointer to the next plane for resources that consist of multiple memory planes.

As a corollary, this mean resources for an image with multiple planes have to be created starting from the highest plane.

resource_changed

Mark a resource as changed so derived internal resources will be recreated on next use.

When importing external images that can't be directly used as texture sampler source, internal copies may have to be created that the hardware can sample from. When those resources are reimported, the image data may have changed, and the previously derived internal resources must be invalidated to avoid sampling from old copies.

resource_destroy

Destroy a resource. A resource is destroyed if it has no more references.

get_timestamp

Query a timestamp in nanoseconds. The returned value should match PIPE_QUERY_TIMESTAMP. This function returns immediately and doesn't wait for rendering to complete (which cannot be achieved with queries).

get_driver_query_info

Return a driver-specific query. If the info parameter is NULL, the number of available queries is returned. Otherwise, the driver query at the specified index is returned in info. The function returns non-zero on success. The driver-specific query is described with the pipe_driver_query_info structure.

get_driver_query_group_info

Return a driver-specific query group. If the info parameter is NULL, the number of available groups is returned. Otherwise, the driver query group at the specified index is returned in info. The function returns non-zero on success. The driver-specific query group is described with the pipe_driver_query_group_info structure.

get_disk_shader_cache

Returns a pointer to a driver-specific on-disk shader cache. If the driver failed to create the cache or does not support an on-disk shader cache NULL is returned. The callback itself may also be NULL if the driver doesn't support an on-disk shader cache.

Thread safety

Screen methods are required to be thread safe. While gallium rendering contexts are not required to be thread safe, it is required to be safe to use different contexts created with the same screen in different threads without locks. It is also required to be safe using screen methods in a thread, while using one of its contexts in another (without locks).