Base class for computation back ends, which may be hardware-accelerated. More...

#include <compute.h>

Inheritance diagram for nngn::Compute:

[legend]

Classes
struct	Buffer

struct	DataArg
	Argument type for raw memory passed to the execution kernel "by value". More...

struct	Events
	Controls dependencies between operations. More...

struct	Handle
	Base class for handles to opaque compute objects. More...

struct	Image

struct	Kernel

struct	OpenCLParameters

struct	Program

struct	Sampler

struct	Version

Public Types
enum class	Backend : u8 { PSEUDOCOMP , OPENCL_BACKEND }
	Indicates which type of back end to create. More...

enum class	DeviceType : u8 { CPU = 1u << 0 , GPU = 1u << 1 }

enum class	Type : u8 { NONE , LOCAL , SCALAR_BEGIN , BYTE = SCALAR_BEGIN , INT , UINT , FLOAT , VECTOR_BEGIN , BYTEV = VECTOR_BEGIN , INTV , UINTV , FLOATV , VECTOR_END = FLOATV , DATA , HANDLE_BEGIN , BUFFER = HANDLE_BEGIN , IMAGE , SAMPLER , HANDLE_END = SAMPLER , N }
	Supported parameter types for kernel execution. More...

enum	MemFlag : u8 { READ_WRITE = 1u << 0 , WRITE_ONLY = 1u << 1 , READ_ONLY = 1u << 2 }
	Properties of memory blocks. More...

enum	ExecFlag : u8 { BLOCKING = 1u << 0 }
	Kernel execution flags. More...

enum	Limit : u8 { COMPUTE_UNITS , WORK_GROUP_SIZE , LOCAL_MEMORY , N }
	Indices for the values accessible via get_limits. More...

enum	ProfInfo : u8 { QUEUED = 1u << 0 , SUBMIT = 1u << 1 , START = 1u << 2 , END = 1u << 3 , PROF_INFO_MAX = END , PROF_INFO_ALL = QUEUED \| SUBMIT \| START \| END }
	Bit mask indicating which profiling data to collect/return. More...

Public Member Functions
virtual bool	init ()=0
	Must be called before the back end can be used.

virtual size_t	n_platforms () const =0

virtual size_t	n_devices () const =0

virtual void	get_limits (u64 *p) const =0
	Writes the information described in Limit into `p`.

std::vector< u64 >	get_limits () const
	Convenience overload that allocates the required memory.

virtual std::string	platform_name () const =0

virtual std::string	device_name () const =0

virtual Buffer	create_buffer (MemFlag flags, std::size_t n, const std::byte *p)=0
	Create a buffer of the specified size.

virtual bool	read_buffer (Buffer b, std::size_t off, std::size_t n, std::byte *p, Events events) const =0

virtual bool	fill_buffer (Buffer b, std::size_t off, std::size_t n, std::byte v, Events events) const =0
	Fills the buffer with `n` copies of `v`.

virtual bool	fill_buffer (Buffer b, std::size_t off, std::size_t n, std::size_t pattern_size, const std::byte *p, Events events) const =0
	Fills the buffer with `n / pattern_size` copies of pattern `p`.

virtual bool	write_buffer (Buffer b, std::size_t off, std::size_t n, const std::byte *p, Events events) const =0

virtual bool	write_buffer_rect (Buffer b, std::array< std::size_t, 3 > buffer_origin, std::array< std::size_t, 3 > host_origin, std::array< std::size_t, 3 > region, std::size_t buffer_row_pitch, std::size_t buffer_slice_pitch, std::size_t host_row_pitch, std::size_t host_slice_pitch, const std::byte *p, Events events) const =0
	Writes a rectangular region of a buffer.

virtual void *	map_buffer (Buffer b, MemFlag flags, std::size_t off, std::size_t n, Events events) const =0

virtual bool	unmap_buffer (Buffer b, void *p, Events events) const =0

template<typename ... Ts>
bool	write_struct (Buffer b, Events events, Ts &&...ts) const
	Writes the variadic arguments sequentially to the buffer.

virtual bool	release_buffer (Buffer b)=0

virtual Image	create_image (Type type, std::size_t w, std::size_t h, MemFlag flags, const std::byte *p)=0
	Create an image of the specified size.

virtual bool	read_image (Image i, std::size_t w, std::size_t h, std::byte *p, Events events) const =0

virtual bool	fill_image (Image i, std::size_t w, std::size_t h, const void *v, Events events) const =0
	Fills the image with copies of `v`.

virtual bool	release_image (Image i)=0

virtual Sampler	create_sampler ()=0

virtual bool	release_sampler (Sampler s)=0

virtual Program	create_program (std::string_view src, const char *opts)=0
	Compiles source into a program using compilation options `opts`.

virtual bool	release_program (Program p)=0

virtual Kernel	create_kernel (Program program, const char func, std::size_t len, const Type types, const std::size_t sizes, const std::byte const *data, Events events)=0

virtual bool	release_kernel (Kernel k)=0

virtual std::size_t	n_events (std::size_t n, const Type *types) const =0
	Number of events generated by execute for arguments `types`.

virtual bool	prof_info (ProfInfo info, std::size_t n, const Event const events, u64 *out) const =0
	Collect profiling information from `n` `events`.

virtual bool	wait (std::size_t n, const Event const v) const =0
	Block until the given `events` have completed.

virtual bool	release_events (std::size_t n, const Event const v) const =0

virtual bool	execute (Kernel kernel, ExecFlag flags, u32 n_dim, const std::size_t global_size, const std::size_t local_size, Events events) const =0

virtual bool	execute (Program program, const std::string &func, ExecFlag flags, u32 n_dim, const std::size_t global_size, const std::size_t local_size, std::size_t len, const Type types, const std::size_t sizes, const std::byte const data, Events events) const =0
	Execute a program with the given arguments.

template<typename ... Ts>
Kernel	create_kernel (Program program, const char *func, Events events, Ts &&...ts)
	Variadic interface for create_kernel.

template<typename ... Ts>
bool	execute (Program program, const std::string &func, ExecFlag flags, u32 n_dim, const std::size_t global_size, const std::size_t local_size, Events events, Ts &&...ts)
	Variadic interface for execute.

template<std::derived_from< Compute::Handle > T>
constexpr auto	arg_type

template<Compute::Type t>
constexpr auto	to_vector_type () -> Type

template<typename ... Ts>
auto	create_kernel (Program program, const char *func, Events events, Ts &&...ts) -> Kernel

Static Public Member Functions
static constexpr bool	is_vector_type (Type t)
	Determines is `t` is one of the `*V` vector values in Type.

static constexpr bool	is_handle_type (Type t)

template<Type t>
static constexpr Type	to_vector_type ()
	Transforms a scalar type into the equivalent vector type.

static std::unique_ptr< Compute >	create (Backend b, const void *params=nullptr)
	Creates a back end of the specified type.

template<>
constexpr auto	arg_type

template<>
constexpr auto	arg_type

template<>
constexpr auto	arg_type

template<>
constexpr auto	arg_type

Static Public Attributes
template<typename T >
static constexpr Type	arg_type = Type::NONE
	Maps supported types to the equivalent Type value.

Detailed Description

Base class for computation back ends, which may be hardware-accelerated.

Member Enumeration Documentation

◆ Backend

enum class nngn::Compute::Backend : u8

strong

Indicates which type of back end to create.

Enumerator

PSEUDOCOMP

No-op back end which can be used in lieu of a real one.

As currently implemented, it is almost always better to not create a back end at all.

OPENCL_BACKEND

OpenCL 1.2 back end.

◆ DeviceType

enum class nngn::Compute::DeviceType : u8

strong

Enumerator
CPU
GPU

◆ ExecFlag

enum nngn::Compute::ExecFlag : u8

Kernel execution flags.

Enumerator

BLOCKING

Block the execution until the operation finishes.

Note that if this flag is not set and no event data is provided (see Events), it will not be possible to determine when the operation finishes.

◆ Limit

enum nngn::Compute::Limit : u8

Indices for the values accessible via get_limits.

Enumerator
COMPUTE_UNITS
WORK_GROUP_SIZE
LOCAL_MEMORY
N

◆ MemFlag

enum nngn::Compute::MemFlag : u8

Properties of memory blocks.

Enumerator
READ_WRITE
WRITE_ONLY
READ_ONLY

◆ ProfInfo

enum nngn::Compute::ProfInfo : u8

Bit mask indicating which profiling data to collect/return.

Enumerator
QUEUED
SUBMIT
START
END
PROF_INFO_MAX
PROF_INFO_ALL

◆ Type

enum class nngn::Compute::Type : u8

strong

Supported parameter types for kernel execution.

Enumerator
NONE	Invalid value.
LOCAL	Device-local memory.
SCALAR_BEGIN
BYTE
INT
UINT
FLOAT
VECTOR_BEGIN
BYTEV
INTV
UINTV
FLOATV
VECTOR_END
DATA	Pointer to raw memory. See also DataArg.
HANDLE_BEGIN
BUFFER
IMAGE
SAMPLER
HANDLE_END
N

Member Function Documentation

◆ arg_type() [1/5]

template<>

auto nngn::Compute::arg_type

staticconstexpr

◆ arg_type() [2/5]

template<>

auto nngn::Compute::arg_type

staticconstexpr

◆ arg_type() [3/5]

template<>

auto nngn::Compute::arg_type

staticconstexpr

◆ arg_type() [4/5]

template<>

auto nngn::Compute::arg_type

staticconstexpr

◆ arg_type() [5/5]

template<std::ranges::range T>

auto nngn::Compute::arg_type< T >

constexpr

Initial value:

=

Compute::to_vector_type<Compute::arg_type<std::ranges::range_value_t<T>>>()

nngn::Compute::to_vector_type

static constexpr Type to_vector_type()

Transforms a scalar type into the equivalent vector type.

◆ create()

std::unique_ptr< Compute > nngn::Compute::create	(	Backend	b,
		const void *	params = nullptr )

static

Creates a back end of the specified type.

The init function must be called (and its return value checked) before it can be used.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ create_buffer()

virtual Buffer nngn::Compute::create_buffer	(	MemFlag	flags,
		std::size_t	n,
		const std::byte *	p )

pure virtual

Create a buffer of the specified size.

Optionally fill it with n bytes starting from p, if not null.

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend.

◆ create_image()

virtual Image nngn::Compute::create_image	(	Type	type,
		std::size_t	w,
		std::size_t	h,
		MemFlag	flags,
		const std::byte *	p )

pure virtual

Create an image of the specified size.

Optionally fill it with w * h bytes starting from p, if not null.

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ create_kernel() [1/3]

template<typename ... Ts>

Kernel nngn::Compute::create_kernel	(	Program	program,
		const char *	func,
		Events	events,
		Ts &&...	ts )

Variadic interface for create_kernel.

See also: execute

◆ create_kernel() [2/3]

template<typename ... Ts>

auto nngn::Compute::create_kernel	(	Program	program,
		const char *	func,
		Events	events,
		Ts &&...	ts ) -> Kernel

Here is the call graph for this function:

◆ create_kernel() [3/3]

virtual Kernel nngn::Compute::create_kernel	(	Program	program,
		const char *	func,
		std::size_t	len,
		const Type *	types,
		const std::size_t *	sizes,
		const std::byte const	data,
		Events	events )

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

Here is the caller graph for this function:

◆ create_program()

virtual Program nngn::Compute::create_program	(	std::string_view	src,
		const char *	opts )

pure virtual

Compiles source into a program using compilation options opts.

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ create_sampler()

virtual Sampler nngn::Compute::create_sampler ( )

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ device_name()

virtual std::string nngn::Compute::device_name ( ) const

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

Here is the caller graph for this function:

◆ execute() [1/3]

virtual bool nngn::Compute::execute	(	Kernel	kernel,
		ExecFlag	flags,
		u32	n_dim,
		const std::size_t *	global_size,
		const std::size_t *	local_size,
		Events	events ) const

pure virtual

Here is the caller graph for this function:

◆ execute() [2/3]

template<typename ... Ts>

bool nngn::Compute::execute	(	Program	program,
		const std::string &	func,
		ExecFlag	flags,
		u32	n_dim,
		const std::size_t *	global_size,
		const std::size_t *	local_size,
		Events	events,
		Ts &&...	ts )

Variadic interface for execute.

All arguments in common with the other function in the overload set have the same semantics.

Parameters

ts These values are used to create temporary (C) arrays that are used as the len, types, sizes, and data arguments of the original function. The values for those arrays are determined via the arg_type, detail::arg_size, and detail::arg_ptr functions, respectively, and must be of supported types (see the arg_type specializations).

Here is the call graph for this function:

◆ execute() [3/3]

virtual bool nngn::Compute::execute	(	Program	program,
		const std::string &	func,
		ExecFlag	flags,
		u32	n_dim,
		const std::size_t *	global_size,
		const std::size_t *	local_size,
		std::size_t	len,
		const Type *	types,
		const std::size_t *	sizes,
		const std::byte const	data,
		Events	events ) const

pure virtual

Execute a program with the given arguments.

Parameters

func	Name of the function to be used as the entry point.
n_dim	Number of dimensions in `global_size` and `local_size`.
len	Length of `types`, `sizes`, and `data`.
types	Type of each argument in `data`.
sizes	Size of each argument in `data`.
data	The argument data. Must have the correct type and size as determined by the corresponding values in `types` and `sizes`.
events	Dependency information, see Events and n_events.

◆ fill_buffer() [1/2]

virtual bool nngn::Compute::fill_buffer	(	Buffer	b,
		std::size_t	off,
		std::size_t	n,
		std::byte	v,
		Events	events ) const

pure virtual

Fills the buffer with n copies of v.

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ fill_buffer() [2/2]

virtual bool nngn::Compute::fill_buffer	(	Buffer	b,
		std::size_t	off,
		std::size_t	n,
		std::size_t	pattern_size,
		const std::byte *	p,
		Events	events ) const

pure virtual

Fills the buffer with n / pattern_size copies of pattern p.

n must be a multiple of pattern_size.

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ fill_image()

virtual bool nngn::Compute::fill_image	(	Image	i,
		std::size_t	w,
		std::size_t	h,
		const void *	v,
		Events	events ) const

pure virtual

Fills the image with copies of v.

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ get_limits() [1/2]

std::vector< u64 > nngn::Compute::get_limits ( ) const

inline

Convenience overload that allocates the required memory.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_limits() [2/2]

virtual void nngn::Compute::get_limits ( u64 * p ) const

pure virtual

Writes the information described in Limit into p.

◆ init()

virtual bool nngn::Compute::init ( )

pure virtual

Must be called before the back end can be used.

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ is_handle_type()

bool nngn::Compute::is_handle_type ( Type t )

inlinestaticconstexpr

Here is the caller graph for this function:

◆ is_vector_type()

bool nngn::Compute::is_vector_type ( Type t )

inlinestaticconstexpr

Determines is t is one of the *V vector values in Type.

Here is the caller graph for this function:

◆ map_buffer()

virtual void * nngn::Compute::map_buffer	(	Buffer	b,
		MemFlag	flags,
		std::size_t	off,
		std::size_t	n,
		Events	events ) const

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ n_devices()

virtual size_t nngn::Compute::n_devices ( ) const

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ n_events()

virtual std::size_t nngn::Compute::n_events	(	std::size_t	n,
		const Type *	types ) const

pure virtual

Number of events generated by execute for arguments types.

Does not include the event generated by the execution itself.

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ n_platforms()

virtual size_t nngn::Compute::n_platforms ( ) const

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ platform_name()

virtual std::string nngn::Compute::platform_name ( ) const

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

Here is the caller graph for this function:

◆ prof_info()

virtual bool nngn::Compute::prof_info	(	ProfInfo	info,
		std::size_t	n,
		const Event const	events,
		u64 *	out ) const

pure virtual

Collect profiling information from n events.

The back end must have been created with debugging information enabled.

◆ read_buffer()

virtual bool nngn::Compute::read_buffer	(	Buffer	b,
		std::size_t	off,
		std::size_t	n,
		std::byte *	p,
		Events	events ) const

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ read_image()

virtual bool nngn::Compute::read_image	(	Image	i,
		std::size_t	w,
		std::size_t	h,
		std::byte *	p,
		Events	events ) const

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ release_buffer()

virtual bool nngn::Compute::release_buffer ( Buffer b )

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ release_events()

virtual bool nngn::Compute::release_events	(	std::size_t	n,
		const Event const	v ) const

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ release_image()

virtual bool nngn::Compute::release_image ( Image i )

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ release_kernel()

virtual bool nngn::Compute::release_kernel ( Kernel k )

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ release_program()

virtual bool nngn::Compute::release_program ( Program p )

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ release_sampler()

virtual bool nngn::Compute::release_sampler ( Sampler s )

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ to_vector_type() [1/2]

template<Type t>

static constexpr Type nngn::Compute::to_vector_type ( )

staticconstexpr

Transforms a scalar type into the equivalent vector type.

E.g. to_vector_type<INT> == INTV. It is an error to apply this function to a non-scalar type.

◆ to_vector_type() [2/2]

template<Compute::Type t>

auto nngn::Compute::to_vector_type ( ) -> Type

inlineconstexpr

◆ unmap_buffer()

virtual bool nngn::Compute::unmap_buffer	(	Buffer	b,
		void *	p,
		Events	events ) const

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ wait()

virtual bool nngn::Compute::wait	(	std::size_t	n,
		const Event const	v ) const

pure virtual

Block until the given events have completed.

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ write_buffer()

virtual bool nngn::Compute::write_buffer	(	Buffer	b,
		std::size_t	off,
		std::size_t	n,
		const std::byte *	p,
		Events	events ) const

pure virtual

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

Here is the caller graph for this function:

◆ write_buffer_rect()

virtual bool nngn::Compute::write_buffer_rect	(	Buffer	b,
		std::array< std::size_t, 3 >	buffer_origin,
		std::array< std::size_t, 3 >	host_origin,
		std::array< std::size_t, 3 >	region,
		std::size_t	buffer_row_pitch,
		std::size_t	buffer_slice_pitch,
		std::size_t	host_row_pitch,
		std::size_t	host_slice_pitch,
		const std::byte *	p,
		Events	events ) const

pure virtual

Writes a rectangular region of a buffer.

Arguments are the same as the OpenCL function clEnqueueCopyBufferRect.

Implemented in anonymous_namespace{opencl.cpp}::OpenCLBackend, and anonymous_namespace{pseudo.cpp}::Pseudocomp.

◆ write_struct()

template<typename ... Ts>

bool nngn::Compute::write_struct	(	Buffer	b,
		Events	events,
		Ts &&...	ts ) const

Writes the variadic arguments sequentially to the buffer.

Supported arguments types are scalar and vector types described in execute.

Here is the call graph for this function:

Member Data Documentation

◆ arg_type

template<typename T >

Type nngn::Compute::arg_type = Type::NONE

staticconstexpr

Maps supported types to the equivalent Type value.

The documentation for this struct was generated from the following files:

src/compute/compute.h
src/compute/compute.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ Backend

◆ DeviceType

◆ ExecFlag

◆ Limit

◆ MemFlag

◆ ProfInfo

◆ Type

Member Function Documentation

◆ arg_type() [1/5]

◆ arg_type() [2/5]

◆ arg_type() [3/5]

◆ arg_type() [4/5]

◆ arg_type() [5/5]

◆ create()

◆ create_buffer()

◆ create_image()

◆ create_kernel() [1/3]

◆ create_kernel() [2/3]

◆ create_kernel() [3/3]

◆ create_program()

◆ create_sampler()

◆ device_name()

◆ execute() [1/3]

◆ execute() [2/3]

◆ execute() [3/3]

◆ fill_buffer() [1/2]

◆ fill_buffer() [2/2]

◆ fill_image()

◆ get_limits() [1/2]

◆ get_limits() [2/2]

◆ init()

◆ is_handle_type()

◆ is_vector_type()

◆ map_buffer()

◆ n_devices()

◆ n_events()

◆ n_platforms()

◆ platform_name()

◆ prof_info()

◆ read_buffer()

◆ read_image()

◆ release_buffer()

◆ release_events()

◆ release_image()

◆ release_kernel()

◆ release_program()

◆ release_sampler()

◆ to_vector_type() [1/2]

◆ to_vector_type() [2/2]

◆ unmap_buffer()

◆ wait()

◆ write_buffer()

◆ write_buffer_rect()

◆ write_struct()

Member Data Documentation

◆ arg_type