Struct grr::Device

pub struct Device(_);

Logical device, representation one or multiple physical devices (hardware or software).

This wraps an existing GL context and acts as the main API interface. It’s the responsibility of the user to keep the context alive.

Implementations

impl Device

pub fn create_buffer(&self, size: u64, memory: MemoryFlags) -> Buffer

Create a new empty buffer.

Parameters

• size: Length in bytes of the associated storage memory.
• memory: Properties of the internal memory slice. Indicating the usage and locality of the allocation.

pub fn map_buffer<T>(
    &self,
    buffer: &Buffer,
    range: Range<u64>,
    mapping: MappingFlags
) -> &mut [T]

Persistently map memory to host accessible virtual memory.

Valid usage

• range.end may not be larger than the size of the buffer.
• range.start must be smaller than range.end
• buffer must be created with CPU_MAP_READ or CPU_MAP_WRITE flags.
• range.end - range.start must be a multiple of the size of T
• If the buffer has not been created with CPU_MAP_READ the host should not read from the returned slice.
• If the buffer has not been created with CPU_MAP_WRITE the host should not write to the returned slice.
• A buffer can not be mapped multiple times.

Return

Returns a typed slice of the mapped memory range.

pub fn unmap_buffer(&self, buffer: &Buffer) -> bool

Unmap a buffer from virtual host memory.

Valid usage

• The buffer must be currently mapped.

pub fn delete_buffer(&self, buffer: Buffer)

Delete a buffer.

impl Device

pub fn bind_vertex_buffers(
    &self,
    vao: &VertexArray,
    first: u32,
    views: &[VertexBufferView<'_>]
)

Bind vertex buffers to a vertex array.

pub fn bind_index_buffer(&self, vao: &VertexArray, buffer: &Buffer)

Bind a index buffer to a vertex array.

pub fn bind_pipeline(&self, pipeline: &Pipeline)

Bind a pipeline for usage.

pub fn set_viewport(&self, first: u32, viewports: &[Viewport])

Set viewport transformation parameters.

The viewport determines the mapping from NDC (normalized device coordinates) into window coordinates.

pub fn set_scissor(&self, first: u32, scissors: &[Region])

Set scissor rectangles for viewports.

Valid usage

• Every active viewport needs an associated scissor.

pub fn draw(
    &self,
    primitive: Primitive,
    vertices: Range<u32>,
    instance: Range<u32>
)

Submit a (non-indexed) draw call.

Valid usage

• There must be a valid graphics pipeline currently bound.
• There must be a calid vertex array currently bound.
• For each attribute in the bound vertex array there must be a vertex buffer bound at the specified binding slot.
• For each attribute in the bound vertex array there must be a vertex attribute specified in the shader with matching format and location.
• The access vertices must be in bound of the vertex buffers bound.
• vertices.end must be larger than vertices.start.
• vertices.end - vertices.start must be allow assembling complete primitives.
• instances.end must be larger than instances.start.

pub fn draw_indexed(
    &self,
    primitive: Primitive,
    index_ty: IndexTy,
    indices: Range<u32>,
    instance: Range<u32>,
    base_vertex: i32
)

Submit an indexed draw call.

Valid usage

• There must be a valid graphics pipeline currently bound.
• There must be a calid vertex array currently bound.
• For each attribute in the bound vertex array there must be a vertex buffer bound at the specified binding slot.
• For each attribute in the bound vertex array there must be a vertex attribute specified in the shader with matching format and location.
• The access vertices must be in bound of the vertex buffers bound.
• indices.end must be larger than indices.start.
• indices.end - indices.start must be allow assembling complete primitives.
• instances.end must be larger than instances.start.

pub fn dispatch(&self, groups_x: u32, groups_y: u32, groups_z: u32)

Dispatch a workgroup for computation.

Valid usage

• group_x, group_y and group_z must be larger than 0.
• There must be a valid compute shader currently bound.

impl Device

pub fn new<F>(loader: F) -> Selfwhere
    F: FnMut(&str) -> *const c_void,

Create a new device from an existing context.

The context must be initialized with GL 4.5+ core. The passed loader is used to obtain the function pointers from the context.

impl Device

pub fn create_framebuffer(&self) -> Framebuffer

pub fn delete_framebuffer(&self, framebuffer: Framebuffer)

pub fn create_renderbuffer(&self) -> Renderbuffer

pub fn delete_renderbuffer(&self, renderbuffer: Renderbuffer)

pub fn clear_attachment(&self, fb: &Framebuffer, cv: ClearAttachment)

Clear framebuffer attachment.

pub fn invalidate_framebuffer(
    &self,
    _framebuffer: &Framebuffer,
    _attachments: &[Attachment],
    _region: Region
)

impl Device

pub fn create_image(&self, ty: ImageType, format: Format, levels: u32) -> Image

pub fn copy_host_to_image(
    &self,
    image: &Image,
    level: u32,
    layers: Range<u32>,
    offset: Offset,
    extent: Extent,
    data: &[u8],
    base_format: BaseFormat,
    format_layout: FormatLayout
)

pub fn create_image_view(
    &self,
    image: &Image,
    ty: ImageViewType,
    format: Format,
    range: SubresourceRange
) -> ImageView

pub fn bind_image_views(&self, first: u32, views: &[&ImageView])

impl Device

pub fn create_sampler(&self, desc: SamplerDesc) -> Sampler

Create a sampler object.

pub fn bind_samplers(&self, first: u32, samplers: &[&Sampler])

Bind samplers to specific texture units.

pub fn delete_sampler(&self, sampler: Sampler)

Delete a sampler.

impl Device

pub fn create_shader(&self, stage: ShaderStage, source: &[u8]) -> Shader

Create a new shader from GLSL.

Valid usage

• source must be a NULL-terminated C-String.
• The GLSL shader version must be 450 core or higher.
• The stage parameter must be a valid stage of the passed shader source.

pub fn delete_shader(&self, shader: Shader)

Delete a shader.

pub fn create_graphics_pipeline(
    &self,
    desc: GraphicsPipelineDesc<'_>
) -> Pipeline

Create a graphics pipeline.

This equals a Program in GL terminology.

Valid usage

• The vertex shader in desc must be valid and created with ShaderStage::Vertex.
• The tessellation control shader in desc must be valid and created with ShaderStage::TessellationControl if specified.
• The tessellation evaluation shader in desc must be valid and created with ShaderStage::TessellationEvalution if specified.
• The geometry shader in desc must be valid and created with ShaderStage::Geometry if specified.
• The fragment shader in desc must be valid and created with ShaderStage::Fragment if specified.

pub fn create_compute_pipeline(&self, compute_shader: &Shader) -> Pipeline

Create a compute pipeline.

This equals a Program in GL terminology.

Valid usage

• The compute shader in must be valid and created with ShaderStage::Compute.

pub fn create_vertex_array(
    &self,
    attributes: &[VertexAttributeDesc]
) -> VertexArray

Create a new vertex array, storing information for the input assembler.

The vertex array specified the vertex attributes and their binding to vertex buffer objects.

pub fn delete_vertex_array(&self, vao: VertexArray)

Delete a vertex array.

pub fn bind_vertex_array(&self, vao: &VertexArray)

Bind a vertex array for usage.