OffsetPointer#

Fully qualified name: cupva::OffsetPointer

Defined in src/host/cpp_api/include/cupva_host.hpp

template<typename T>
class OffsetPointer : public std::conditional_t<std::is_const<T>::value, priv::ByteOffsetPointer<uint8_t const>, priv::ByteOffsetPointer<uint8_t>>#

The OffsetPointer object is used to represent a mutable device pointer.

This object is designed to store memory addresses in a split representation: base address and offset pair. This representation is useful in scenarios where the exact address (base) is unknown at the dma compilation time or changes afterwards. Internally, the pointer stores the base address and offset separately. Base address is shared among object copies, while offset is instance specific. All arithmetic operations on an instance manipulate only the offset field.

By replacing raw pointers with OffsetPointer objects, the user can update the pointer values at a later time (for example, during a frame rendering loop) without being forced to recompile the entire DMA configuration. See also CmdProgram::updateDataFlows().

Note that only the base address can be updated in this way. Metadata associated with special device pointer allocations, ie cupva::mem::BufferType::SURFACE pointers, will be ignored at update time. This metadata is only factored in at compile time. See also CmdProgram::compileDataFlows().

CUPVA functions which accept OffsetPointer objects accept either OffsetPointer<void> or OffsetPointer<void const>. An OffsetPointer<void const> may be implicitly converted from any other OffsetPointer, and an OffsetPointer<void> may be implicitly converted from any OffsetPointer<T> where T is non-const. This is analogous to the C language rules for ordinary void pointers.

Template Parameters:

T – Pointer data-type.

Public Types

using PointedToType = T#

Type of pointed-to object.

Public Functions

inline OffsetPointer() noexcept#

Construct an empty object.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

inline OffsetPointer(const OffsetPointer &op) noexcept#

Copy constructor.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

op – is a reference to a source pointer.

inline OffsetPointer &operator=(const OffsetPointer &op) & noexcept#

Copy assignment.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

op – is a reference to a source pointer.

inline OffsetPointer(OffsetPointer &&op) noexcept#

Move constructor.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

op – is a reference to a source pointer.

inline OffsetPointer &operator=(OffsetPointer &&op) & noexcept#

Move assignment.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

op – is a reference to a source pointer.

~OffsetPointer() noexcept = default#

Destructor.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: No

    • De-Init: Yes

template<typename U, CanInitFrom<U> = 0>
inline OffsetPointer(
const OffsetPointer<U> &op,
) noexcept#

Constructor to copy from a different OffsetPointer type.

This constructor exists in the following cases: 1) T is const, U has same underlying type (U may differ in constness) 2) T is const void 3) T is void, U is non-const

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

op – is a reference to a source pointer.

template<typename U, CanInitFrom<U> = 0>
inline auto operator=(
const OffsetPointer<U> &op,
) & noexcept -> OffsetPointer&#

Copy assignment from a different OffsetPointer type.

This constructor exists in the following cases: 1) T is const, U has same underlying type (U may differ in constness) 2) T is const void 3) T is void, U is non-const

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

op – is a reference to a source pointer.

template<typename U, CanInitFrom<U> = 0>
inline OffsetPointer(
OffsetPointer<U> &&op,
) noexcept#

Constructor to move from a different OffsetPointer type.

This constructor exists in the following cases: 1) T is const, U has same underlying type (U may differ in constness) 2) T is const void 3) T is void, U is non-const

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameters:

op – is a reference to a source pointer.

template<typename U, CanInitFrom<U> = 0>
inline auto operator=(
OffsetPointer<U> &&op,
) & noexcept -> OffsetPointer&#

Move assignment from a different OffsetPointer type.

This constructor exists in the following cases: 1) T is const, U has same underlying type (U may differ in constness) 2) T is const void 3) T is void, U is non-const

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameters:

op – is a reference to a source pointer.

inline void setBase(T *ptr)#

Set the base pointer value and reset offset to zero.

Set the base pointer value which is shared between the group of all OffsetPointers created via copy or returned from arithmetic. The offset for this instance is reset to zero. The offsets for other OffsetPointers which share this base pointer will remain unchanged.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Parameters:

ptr – The new device pointer to be set as a base address. The current active context will be used to resolve this device pointer.

Throws:

  • cupva::Exception(UninitializedObject) – if object was not constructed via Create

  • cupva::Exception(InvalidArgument) – if ptr is not a valid device pointer in the Context current to the calling thread

inline cupva::MemType getMemType() const noexcept#

Get the pointer memory type.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: Yes

  • API group

    • Init: No

    • Runtime: Yes

    • De-Init: No

Returns:

MemType The underlying memory type of the stored pointer.

template<typename U = T, CanDoArithmetic<U> = 0>
inline auto operator+=(
std::ptrdiff_t const rhs,
) & noexcept -> OffsetPointer&#

Adds to the offset stored in this pointer instance.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

rhs – The offset increment in T.

Returns:

OffsetPointer& The reference to this object.

template<typename U = T, CanDoArithmetic<U> = 0>
inline auto operator-=(
std::ptrdiff_t const rhs,
) & noexcept -> OffsetPointer&#

Subtracts from the offset stored in this pointer instance.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: No

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

rhs – The offset decrement in T.

Returns:

OffsetPointer& The reference to this object.

template<typename U = T, CanDoArithmetic<U> = 0>
inline auto operator+(
std::ptrdiff_t const rhs,
) const & noexcept -> OffsetPointer#

Increments the pointer (offset) and returns the result in a copy.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: Yes

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

rhs – The offset increment in T.

Returns:

OffsetPointer instance containing the result.

template<typename U = T, CanDoArithmetic<U> = 0>
inline auto operator-(
std::ptrdiff_t const rhs,
) const & noexcept -> OffsetPointer#

Decrements the pointer (offset) and returns the result in a copy.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: Yes

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

rhs – The offset decrement in T.

Returns:

OffsetPointer instance containing the result.

template<typename U, std::enable_if_t<std::is_same<std::remove_cv_t<T>, std::remove_cv_t<U>>::value, int> = 0>
inline std::ptrdiff_t operator-(
const cupva::OffsetPointer<U> &rhs,
) const &#

Take the difference between two offset pointers.

The difference between two offset pointers is valid if they share a base. Offset pointers share a base if they are both copied from, or results of arithmetic on, a shared root object returned from a call to OffsetPointer::Create.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: Yes

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

rhs – RHS of subtraction operator

Throws:

  • cupva::Exception(UninitializedObject) – if either object is not initialized

  • cuvpa::Exception(InvalidArgument) – if OffsetPointers were not created by copying from/arithmetic on the same root object

Returns:

ptrdiff_t representing difference in T between the pointers

Public Static Functions

static inline auto Create(
cupva::MemType const type,
T *const basePtr = nullptr,
) -> OffsetPointer#

OffsetPointer factory method.

Usage considerations

  • Allowed context for the API call

    • Thread-safe: Yes

  • API group

    • Init: Yes

    • Runtime: No

    • De-Init: No

Parameters:

  • type – is the memory type of the underlying pointer.

  • basePtr – initial pointer value.

Throws:

std::bad_alloc – if memory could not be allocated