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.

Methods

impl Device

pub fn create_buffer(&self, size: u64, memory: MemoryFlags) -> Result<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 create_buffer_from_host(
    &self,
    data: &[u8],
    memory: MemoryFlags
) -> Result<Buffer>

Create a new buffer from host memory data.

Parameters

• data: Host data, which will copied into the buffer on creation.
• 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.

Return

Returns if the unmapping operation was successfull.

pub fn delete_buffer(&self, buffer: Buffer)

Delete a buffer.

pub fn delete_buffers(&self, buffers: &[Buffer])

Delete multiple buffers.

pub fn copy_host_to_buffer(&self, buffer: &Buffer, offset: isize, data: &[u8])

Copy memory from the host into the buffer memory.

pub fn copy_buffer(
    &self,
    src_buffer: &Buffer,
    src_offset: isize,
    dst_buffer: &Buffer,
    dst_offset: isize,
    size: u64
)

Copy data from one buffer into another buffer.

pub fn fill_buffer(
    &self,
    buffer: BufferRange,
    buffer_format: Format,
    base_format: BaseFormat,
    format_layout: FormatLayout,
    value: &[u8]
)

Fill buffer with data.

pub fn bind_uniform_buffers(&self, first: u32, ranges: &[BufferRange])

Bind buffer ranges as uniform buffers.

Shader can access the buffer memory as readonly.

pub fn bind_shader_storage_buffers(&self, first: u32, ranges: &[BufferRange])

Bind buffer ranges as shader storage buffers.

Shaders can access the buffer memory as readwrite.

pub fn bind_draw_indirect_buffer(&self, buffer: &Buffer)

Bind indirect buffer for draw commands.

pub fn bind_dispatch_indirect_buffer(&self, buffer: &Buffer)

Bind indirect buffer for dispatch commands.

impl Device

pub fn bind_uniform_constants(
    &self,
    pipeline: &Pipeline,
    first: u32,
    constants: &[Constant]
)

Set uniform constants for a pipeline.

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

Set viewport transformation parameters.

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

See Viewport for more information about the viewport transformation.

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 allow to assemble complete primitives.
• instances.end must be larger than instances.start.

pub fn draw_indirect(
    &self,
    primitive: Primitive,
    offset: u64,
    count: u32,
    stride: u32
)

Submit an indirect draw call.

Valid Usage

• There must be a valid graphics pipeline currently bound.
• There must be a valid draw indirect buffer currently bound.

pub fn draw_indirect_from_host(
    &self,
    primitive: Primitive,
    data: &[DrawIndirectCmd]
)

Submit an indirect draw call.

pub fn draw_indexed_indirect(
    &self,
    primitive: Primitive,
    index_ty: IndexTy,
    offset: u64,
    count: u32,
    stride: u32
)

Indirect draw call.

pub fn draw_indexed_indirect_from_host(
    &self,
    primitive: Primitive,
    index_ty: IndexTy,
    data: &[DrawIndexedIndirectCmd]
)

Indirect (indexed) draw call.

pub fn dispatch(&self, x: u32, y: u32, z: u32)

Dispatch a workgroup for computation.

Valid usage

• There must be a valid compute shader currently bound.

pub fn dispatch_indirect(&self, offset: u64)

impl Device

pub fn object_name<T: Object>(&self, object: &T, name: &str)

Associate a name with an object.

pub fn enable_debug_message(
    &self,
    src: Filter<DebugSource>,
    ty: Filter<DebugType>,
    flags: DebugReport,
    ids: Option<&[u32]>
)

pub fn disable_debug_message(
    &self,
    src: Filter<DebugSource>,
    ty: Filter<DebugType>,
    flags: DebugReport,
    ids: Option<&[u32]>
)

pub fn begin_debug_marker(&self, src: DebugSource, id: u32, msg: &str)

pub fn end_debug_marker(&self)

impl Device

pub fn new<F>(
    loader: F,
    debug: Debug<fn(_: DebugReport, _: DebugSource, _: DebugType, _: u32, _: &str)>
) -> Self where
    F: FnMut(&str) -> *const c_void, 

Create a new device from an existing context.

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

pub fn limits(&self) -> DeviceLimits

pub fn features(&self) -> DeviceFeatures

impl Device

pub fn create_framebuffer(&self) -> Result<Framebuffer>

Create a new framebuffer.

pub fn delete_framebuffer(&self, framebuffer: Framebuffer)

Delete a framebuffer.

pub fn delete_framebuffers(&self, framebuffers: &[Framebuffer])

Delete multiple framebuffers.

pub fn create_renderbuffer(&self) -> Result<Renderbuffer>

Create a new framebuffer.

pub fn delete_renderbuffer(&self, renderbuffer: Renderbuffer)

Delete a renderbuffer.

pub fn delete_renderbuffers(&self, renderbuffers: &[Renderbuffer])

Delete multiple renderbuffers.

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

Clear framebuffer attachment.

pub fn invalidate_attachments(
    &self,
    framebuffer: &Framebuffer,
    attachments: &[Attachment],
    region: Region
)

pub fn bind_framebuffer(&self, framebuffer: &Framebuffer)

Bind a framebuffer for draw commands.

pub fn bind_attachments(
    &self,
    framebuffer: &Framebuffer,
    color_attachments: &[AttachmentView],
    depth_stencil_attachment: Option<AttachmentView>
)

Bind attachments to the framebuffer.

All previously bound attachments become invalid.

pub fn set_color_attachments(
    &self,
    framebuffer: &Framebuffer,
    attachments: &[u32]
)

Specify color attachments.

Defines the color render targets for the next draw calls. This builds the link between fragment outputs in the fragment shader and attachments bound on the framebuffer.

impl Device

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

pub fn delete_image(&self, image: Image)

Delete an images.

pub fn delete_images(&self, images: &[Image])

Delete multiple images.

pub fn copy_host_to_image<T>(
    &self,
    image: &Image,
    subresource: SubresourceLevel,
    offset: Offset,
    extent: Extent,
    data: &[T],
    layout: SubresourceLayout
)

Copy image data from host memory to device memory.

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

Create an image view from an image.

pub fn delete_image_view(&self, view: ImageView)

Delete an image views.

pub fn delete_image_views(&self, views: &[ImageView])

Delete multipe image views.

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

Bind image views to texture units.

pub fn generate_mipmaps(&self, image: &Image)

Generate mipmaps.

This generates the remaining mipmap levels using the base layer via downscaling. The number of levels are determined on resource creation.

The downscaling filter is implementation dependent!

impl Device

pub fn create_shader(&self, stage: ShaderStage, source: &[u8]) -> Result<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 delete_shaders(&self, shaders: &[Shader])

Delete multiple shaders.

pub fn create_graphics_pipeline(
    &self,
    desc: GraphicsPipelineDesc
) -> Result<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
) -> Result<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 delete_pipeline(&self, pipeline: Pipeline)

Delete a pipeline.

pub fn delete_pipelines(&self, pipelines: &[Pipeline])

Delete multiple pipelines.

pub fn bind_input_assembly_state(&self, state: &InputAssembly)

Bind input assembly pipeline state.

pub fn bind_color_blend_state(&self, state: &ColorBlend)

Bind color blending pipeline state.

pub fn bind_depth_stencil_state(&self, state: &DepthStencil)

Bind depth-stencil pipeline state.

Examples

Basic Less-Equal depth test with write:

grr.bind_depth_stencil_state(&grr::DepthStencil {
    depth_test: true,
    depth_write: true,
    depth_compare_op: grr::Compare::LessEqual,
    stencil_test: false,
    stencil_front: grr::StencilFace::KEEP,
    stencil_back: grr::StencilFace::KEEP,
});

pub fn bind_rasterization_state(&self, state: &Rasterization)

Bind rasterization pipeline state.

pub fn bind_multisample_state(&self, state: Option<&Multisample>)

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

Bind a pipeline for usage.

impl Device

pub fn create_query(&self, ty: QueryType) -> Query

pub fn begin_query(&self, query: &Query)

pub fn end_query(&self, query: &Query)

pub fn write_timestamp(&self, query: &Query)

pub fn begin_conditional_rendering(&self, query: &Query, mode: ConditionalMode)

pub fn end_conditional_rendering(&self)

impl Device

pub fn create_sampler(&self, desc: SamplerDesc) -> Result<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)

pub fn delete_samplers(&self, samplers: &[Sampler])

Delete multiple samplers.

impl Device

pub fn memory_barrier(&self, flags: Barrier)

pub fn memory_barrier_by_region(&self, flags: RegionBarrier)

impl Device

pub fn create_vertex_array(
    &self,
    attributes: &[VertexAttributeDesc]
) -> Result<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 delete_vertex_arrays(&self, vao: &[VertexArray])

Delete multiple vertex arrays.

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

Bind a vertex array for usage.

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.