| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Graphics.Vulkan.Marshal
Contents
Description
This module is not part of auto-generated code based on vk.xml. Instead, it is hand-written to provide common types and classes.
- data FlagType
- type FlagMask = FlagMask
- type FlagBit = FlagBit
- class VulkanMarshal a where
- type StructFields a :: [Symbol]
- type CUnionType a :: Bool
- type ReturnedOnly a :: Bool
- type StructExtends a :: [Type]
- class VulkanMarshalPrim a
- class VulkanPtr ptr where
- newtype VkPtr a = VkPtr Word64
- pattern VK_NULL_HANDLE :: forall ptr a. (Eq (ptr a), VulkanPtr ptr) => ptr a
- pattern VK_NULL :: forall ptr a. (Eq (ptr a), VulkanPtr ptr) => ptr a
- clearStorable :: Storable a => Ptr a -> IO ()
- withPtr :: VulkanMarshal a => a -> (Ptr a -> IO b) -> IO b
- class HasField fname a where
- type FieldType fname a :: Type
- type FieldOptional fname a :: Bool
- type FieldOffset fname a :: Nat
- type FieldIsArray fname a :: Bool
- class (HasField fname a, IsFieldArray fname a False) => CanReadField fname a where
- class CanReadField fname a => CanWriteField fname a where
- class (HasField fname a, IndexInBounds fname idx a, IsFieldArray fname a True) => CanReadFieldArray fname idx a where
- type FieldArrayLength fname a :: Nat
- class CanReadFieldArray fname idx a => CanWriteFieldArray fname idx a where
- type IsFieldArray s a e = IsFieldArray' s a (FieldIsArray s a) e
- type IndexInBounds s i a = IndexInBounds' s i a (CmpNat i (FieldArrayLength s a))
- mallocForeignPtr :: Storable a => IO (ForeignPtr a)
- withForeignPtr :: ForeignPtr a -> (Ptr a -> IO b) -> IO b
- addForeignPtrFinalizer :: FinalizerPtr a -> ForeignPtr a -> IO ()
- data Int8 :: *
- data Int16 :: *
- data Int32 :: *
- data Int64 :: *
- data Word8 :: *
- data Word16 :: *
- data Word32 :: *
- data Word64 :: *
- data Ptr a :: * -> *
- data FunPtr a :: * -> *
- data Void :: *
- type CString = Ptr CChar
- newtype CInt :: * = CInt Int32
- newtype CSize :: * = CSize Word64
- newtype CChar :: * = CChar Int8
- newtype CWchar :: * = CWchar Int32
- newtype CULong :: * = CULong Word64
- withCStringField :: forall fname a b. (CanReadFieldArray fname 0 a, FieldType fname a ~ CChar, VulkanMarshal a) => a -> (CString -> IO b) -> IO b
- unsafeCStringField :: forall fname a. (CanReadFieldArray fname 0 a, FieldType fname a ~ CChar, VulkanMarshal a) => a -> CString
- getStringField :: forall fname a. (CanReadFieldArray fname 0 a, FieldType fname a ~ CChar, VulkanMarshal a) => a -> String
- readStringField :: forall fname a. (CanReadFieldArray fname 0 a, FieldType fname a ~ CChar, VulkanMarshal a) => Ptr a -> IO String
- writeStringField :: forall fname a. (CanWriteFieldArray fname 0 a, FieldType fname a ~ CChar, VulkanMarshal a) => Ptr a -> String -> IO ()
- cmpCStrings :: CString -> CString -> Ordering
- cmpCStringsN :: CString -> CString -> Int -> Ordering
Documentation
Distinguish single bits and bitmasks in vulkan flags
class VulkanMarshal a where Source #
All Vulkan structures are stored as-is in byte arrays to avoid any overheads for wrapping and unwrapping haskell values. VulkanMarshal provides an interfaces to write and read these structures in an imperative way.
Associated Types
type StructFields a :: [Symbol] Source #
Names of fields in vulkan structure or union, in the same order as they appear in C typedef.
type CUnionType a :: Bool Source #
Whether this type is a C union. Otherwise this is a C structure.
type ReturnedOnly a :: Bool Source #
Notes that this struct or union is going to be filled in by the API, rather than an application filling it out and passing it to the API.
type StructExtends a :: [Type] Source #
Comma-separated list of structures whose "pNext" can include this type.
Methods
newVkData :: (Ptr a -> IO ()) -> IO a Source #
Allocate a pinned aligned byte array to keep vulkan data structure and fill it using a foreign function.
Note, the function is supposed to use newAlignedPinnedByteArray#
and does not guarantee to fill memory with zeroes.
Use clearStorable to make sure all bytes are set to zero.
Note, the memory is managed by GHC, thus no need for freeing it manually.
newVkData :: (Storable a, VulkanMarshalPrim a) => (Ptr a -> IO ()) -> IO a Source #
Allocate a pinned aligned byte array to keep vulkan data structure and fill it using a foreign function.
Note, the function is supposed to use newAlignedPinnedByteArray#
and does not guarantee to fill memory with zeroes.
Use clearStorable to make sure all bytes are set to zero.
Note, the memory is managed by GHC, thus no need for freeing it manually.
mallocVkData :: IO a Source #
Allocate a pinned aligned byte array to keep vulkan data structure.
Note, the function is supposed to use newAlignedPinnedByteArray#
and does not guarantee to fill memory with zeroes.
Use clearStorable to make sure all bytes are set to zero.
Note, the memory is managed by GHC, thus no need for freeing it manually.
mallocVkData :: (Storable a, VulkanMarshalPrim a) => IO a Source #
Allocate a pinned aligned byte array to keep vulkan data structure.
Note, the function is supposed to use newAlignedPinnedByteArray#
and does not guarantee to fill memory with zeroes.
Use clearStorable to make sure all bytes are set to zero.
Note, the memory is managed by GHC, thus no need for freeing it manually.
mallocVkDataArray :: Int -> IO (Ptr a, [a]) Source #
Allocate a pinned aligned byte array to keep vulkan data structures. Returned `Ptr a` points to the first element in the contiguous array of returned structures. Returned list elements point to the same memory area. This function is unsafe in two ways:
- Several structures are stored next to each other, with no gaps; it would break its alignment if the size is not multiple of alignment.
- Returned pointer is not tracked by GHC as a reference to the managed memory. Thus, the array can be GCed if all references to the returned list are lost.
Note, the function is supposed to use newAlignedPinnedByteArray#
and does not guarantee to fill memory with zeroes.
Use clearStorable to make sure all bytes are set to zero.
Note, the memory is managed by GHC, thus no need for freeing it manually.
mallocVkDataArray :: (Storable a, VulkanMarshalPrim a) => Int -> IO (Ptr a, [a]) Source #
Allocate a pinned aligned byte array to keep vulkan data structures. Returned `Ptr a` points to the first element in the contiguous array of returned structures. Returned list elements point to the same memory area. This function is unsafe in two ways:
- Several structures are stored next to each other, with no gaps; it would break its alignment if the size is not multiple of alignment.
- Returned pointer is not tracked by GHC as a reference to the managed memory. Thus, the array can be GCed if all references to the returned list are lost.
Note, the function is supposed to use newAlignedPinnedByteArray#
and does not guarantee to fill memory with zeroes.
Use clearStorable to make sure all bytes are set to zero.
Note, the memory is managed by GHC, thus no need for freeing it manually.
unsafePtr :: a -> Ptr a Source #
Get pointer to vulkan structure. Note, the address is only valid as long as a given vulkan structure exists. Structures created with newVkData are stored in pinned byte arrays, so their memory is maintained by Haskell GC.
unsafePtr :: VulkanMarshalPrim a => a -> Ptr a Source #
Get pointer to vulkan structure. Note, the address is only valid as long as a given vulkan structure exists. Structures created with newVkData are stored in pinned byte arrays, so their memory is maintained by Haskell GC.
fromForeignPtr :: ForeignPtr a -> IO a Source #
Get vulkan structure referenced by a ForeignPtr trying to avoid copying data.
This function does copy data if called on an unmanaged ForeignPtr
(i.e. one created from ordinary Ptr using something like newForeignPtr.).
This function does not copy data if called on a managed ForeignPtr
(i.e. one created using mallocForeignPtr, or toForeignPtr, or toPlainForeignPtr).
Note, fromForeignPtr does not copy finalizers of ForeignPtr.
Thus, if all references to original ForeignPtr are lost,
its attached finalizers may run even if the created structure is alive.
fromForeignPtr :: (Storable a, VulkanMarshalPrim a) => ForeignPtr a -> IO a Source #
Get vulkan structure referenced by a ForeignPtr trying to avoid copying data.
This function does copy data if called on an unmanaged ForeignPtr
(i.e. one created from ordinary Ptr using something like newForeignPtr.).
This function does not copy data if called on a managed ForeignPtr
(i.e. one created using mallocForeignPtr, or toForeignPtr, or toPlainForeignPtr).
Note, fromForeignPtr does not copy finalizers of ForeignPtr.
Thus, if all references to original ForeignPtr are lost,
its attached finalizers may run even if the created structure is alive.
toForeignPtr :: a -> IO (ForeignPtr a) Source #
Create a ForeignPtr referencing the structure without copying data.
toForeignPtr :: VulkanMarshalPrim a => a -> IO (ForeignPtr a) Source #
Create a ForeignPtr referencing the structure without copying data.
toPlainForeignPtr :: a -> IO (ForeignPtr a) Source #
Create a ForeignPtr referencing the structure without copying data.
This version of a pointer carries no finalizers.
It is not possible to add a finalizer to a ForeignPtr created with
toPlainForeignPtr.
Attempts to add a finalizer to a ForeignPtr created this way, or to
finalize such a pointer, will throw an exception.
toPlainForeignPtr :: VulkanMarshalPrim a => a -> IO (ForeignPtr a) Source #
Create a ForeignPtr referencing the structure without copying data.
This version of a pointer carries no finalizers.
It is not possible to add a finalizer to a ForeignPtr created with
toPlainForeignPtr.
Attempts to add a finalizer to a ForeignPtr created this way, or to
finalize such a pointer, will throw an exception.
touchVkData :: a -> IO () Source #
Make sure this data is alive at a given point in a sequence of IO actions.
touchVkData :: VulkanMarshalPrim a => a -> IO () Source #
Make sure this data is alive at a given point in a sequence of IO actions.
Instances
class VulkanMarshalPrim a Source #
This class gives low-level access to memory location occupied by Vulkan data.
Meant for internal use only.
Minimal complete definition
Instances
class VulkanPtr ptr where Source #
Unify dispatchable and non-dispatchable vulkan pointer types.
Dispatchable handles are represented as Ptr.
Non-dispatchable handles are represented as VkPtr.
Minimal complete definition
VK_DEFINE_NON_DISPATCHABLE_HANDLE
Non-dispatchable handles are represented as VkPtr
Represented as Word64
#if !defined(VK_DEFINE_NON_DISPATCHABLE_HANDLE)
#if defined(__LP64__) || defined(_WIN64) || (defined(__x86_64__) && !defined(__ILP32__) ) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__)
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object;
#else
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;
#endif
#endif
pattern VK_NULL_HANDLE :: forall ptr a. (Eq (ptr a), VulkanPtr ptr) => ptr a Source #
#define VK_NULL_HANDLE 0
pattern VK_NULL :: forall ptr a. (Eq (ptr a), VulkanPtr ptr) => ptr a Source #
Null pointer (either dispatchable or non-dispatchable)
clearStorable :: Storable a => Ptr a -> IO () Source #
Fill all bytes to zero getting data size from Storable instance.
withPtr :: VulkanMarshal a => a -> (Ptr a -> IO b) -> IO b Source #
Run some operation with a pointer to vulkan structure.
Should be used with care:
the structure pretends to be immutable, so it is better to only read
from the pointed memory area, not to write.
If an action needs to write something to the pointer, use newVkData.
Type-indexed access to struct members
class HasField fname a where Source #
Describe fields of a vulkan structure or union.
Minimal complete definition
Associated Types
type FieldType fname a :: Type Source #
Type of a field in a vulkan structure or union.
type FieldOptional fname a :: Bool Source #
Whether this field marked optional in vulkan specification.
Usually, this means that VK_NULL can be written in place
of this field.
type FieldOffset fname a :: Nat Source #
Offset of a field in bytes.
type FieldIsArray fname a :: Bool Source #
Whether this field is a fixed-length array stored directly in a struct.
Methods
fieldOptional :: Bool Source #
Whether this field marked optional in vulkan specification.
Usually, this means that VK_NULL can be written in place
of this field.
fieldOffset :: Int Source #
Offset of a field in bytes.
Instances
class (HasField fname a, IsFieldArray fname a False) => CanReadField fname a where Source #
Instances
class CanReadField fname a => CanWriteField fname a where Source #
Minimal complete definition
Instances
class (HasField fname a, IndexInBounds fname idx a, IsFieldArray fname a True) => CanReadFieldArray fname idx a where Source #
Minimal complete definition
Associated Types
type FieldArrayLength fname a :: Nat Source #
Length of an array that is a field of a structure or union
Methods
fieldArrayLength :: Int Source #
Length of an array that is a field of a structure or union
getFieldArray :: a -> FieldType fname a Source #
Instances
class CanReadFieldArray fname idx a => CanWriteFieldArray fname idx a where Source #
Minimal complete definition
Instances
type IsFieldArray s a e = IsFieldArray' s a (FieldIsArray s a) e Source #
type IndexInBounds s i a = IndexInBounds' s i a (CmpNat i (FieldArrayLength s a)) Source #
Re-exported functions from ForeignPtr
mallocForeignPtr :: Storable a => IO (ForeignPtr a) #
Allocate some memory and return a ForeignPtr to it. The memory
will be released automatically when the ForeignPtr is discarded.
mallocForeignPtr is equivalent to
do { p <- malloc; newForeignPtr finalizerFree p }although it may be implemented differently internally: you may not
assume that the memory returned by mallocForeignPtr has been
allocated with malloc.
GHC notes: mallocForeignPtr has a heavily optimised
implementation in GHC. It uses pinned memory in the garbage
collected heap, so the ForeignPtr does not require a finalizer to
free the memory. Use of mallocForeignPtr and associated
functions is strongly recommended in preference to newForeignPtr
with a finalizer.
withForeignPtr :: ForeignPtr a -> (Ptr a -> IO b) -> IO b #
This is a way to look at the pointer living inside a
foreign object. This function takes a function which is
applied to that pointer. The resulting IO action is then
executed. The foreign object is kept alive at least during
the whole action, even if it is not used directly
inside. Note that it is not safe to return the pointer from
the action and use it after the action completes. All uses
of the pointer should be inside the
withForeignPtr bracket. The reason for
this unsafeness is the same as for
unsafeForeignPtrToPtr below: the finalizer
may run earlier than expected, because the compiler can only
track usage of the ForeignPtr object, not
a Ptr object made from it.
This function is normally used for marshalling data to
or from the object pointed to by the
ForeignPtr, using the operations from the
Storable class.
addForeignPtrFinalizer :: FinalizerPtr a -> ForeignPtr a -> IO () #
This function adds a finalizer to the given foreign object. The finalizer will run before all other finalizers for the same object which have already been registered.
Re-exported common types
8-bit signed integer type
16-bit signed integer type
32-bit signed integer type
64-bit signed integer type
8-bit unsigned integer type
16-bit unsigned integer type
32-bit unsigned integer type
64-bit unsigned integer type
A value of type Ptr aa.
The type a will often be an instance of class
Storable which provides the marshalling operations.
However this is not essential, and you can provide your own operations
to access the pointer. For example you might write small foreign
functions to get or set the fields of a C struct.
Instances
| VulkanPtr Ptr Source # | |
| Eq (Ptr a) | |
| Data a => Data (Ptr a) | |
| Functor (URec (Ptr ())) | |
| Ord (Ptr a) | |
| Show (Ptr a) | |
| Foldable (URec (Ptr ())) | |
| Traversable (URec (Ptr ())) | |
| Generic1 (URec (Ptr ())) | |
| Storable (Ptr a) | |
| Eq (URec (Ptr ()) p) | |
| Ord (URec (Ptr ()) p) | |
| Generic (URec (Ptr ()) p) | |
| type Rep1 (URec (Ptr ())) | |
| data URec (Ptr ()) | Used for marking occurrences of |
| type Rep (URec (Ptr ()) p) | |
A value of type FunPtr aa will normally be a foreign type,
a function type with zero or more arguments where
- the argument types are marshallable foreign types,
i.e.
Char,Int,Double,Float,Bool,Int8,Int16,Int32,Int64,Word8,Word16,Word32,Word64,PtraFunPtraStablePtranewtype. - the return type is either a marshallable foreign type or has the form
IOttis a marshallable foreign type or().
A value of type FunPtr a
foreign import ccall "stdlib.h &free" p_free :: FunPtr (Ptr a -> IO ())
or a pointer to a Haskell function created using a wrapper stub
declared to produce a FunPtr of the correct type. For example:
type Compare = Int -> Int -> Bool foreign import ccall "wrapper" mkCompare :: Compare -> IO (FunPtr Compare)
Calls to wrapper stubs like mkCompare allocate storage, which
should be released with freeHaskellFunPtr when no
longer required.
To convert FunPtr values to corresponding Haskell functions, one
can define a dynamic stub for the specific foreign type, e.g.
type IntFunction = CInt -> IO () foreign import ccall "dynamic" mkFun :: FunPtr IntFunction -> IntFunction
Uninhabited data type
Since: 4.8.0.0
Haskell type representing the C int type.
Haskell type representing the C size_t type.
Haskell type representing the C char type.
Haskell type representing the C wchar_t type.
Haskell type representing the C unsigned long type.
Utilities for string types
withCStringField :: forall fname a b. (CanReadFieldArray fname 0 a, FieldType fname a ~ CChar, VulkanMarshal a) => a -> (CString -> IO b) -> IO b Source #
Perform an action on a C string field. The string pointers should not be used outside the callback. It will point to a correct location only as long as the struct is alive.
unsafeCStringField :: forall fname a. (CanReadFieldArray fname 0 a, FieldType fname a ~ CChar, VulkanMarshal a) => a -> CString Source #
Get pointer to a memory location of the C string field in a structure.
getStringField :: forall fname a. (CanReadFieldArray fname 0 a, FieldType fname a ~ CChar, VulkanMarshal a) => a -> String Source #
readStringField :: forall fname a. (CanReadFieldArray fname 0 a, FieldType fname a ~ CChar, VulkanMarshal a) => Ptr a -> IO String Source #
writeStringField :: forall fname a. (CanWriteFieldArray fname 0 a, FieldType fname a ~ CChar, VulkanMarshal a) => Ptr a -> String -> IO () Source #