Types.hs

{-|
The plain vocabulary types shared across the library.

Versioned resource handles and queue / timeline / event identities.
-}
module Fragr.Types
  ( Handle (..)
  , handleId
  , SomeHandle (..)
  , someHandleId
  , QueueId (..)
  , defaultQueue
  , FamilyId (..)
  , EventId (..)
  ) where

{- |
A handle to one /version/ of a virtual resource of type @r@. Handles are
cheap value types; a handle is valid ('Fragr.Graph.isValid') iff it names the latest
version of its resource. A handle superseded by a later 'Fragr.Builder.write' is
/stale/ and must not be used again.

The resource type rides along from 'Fragr.Builder.create' / 'Fragr.Graph.importResource', so
declarations take the right 'Fragr.Resource.Flags' and 'Fragr.Exec.get' needs no type
application — passing another resource's flags or fetching at the wrong
type is a type error, not a runtime one.
-}
newtype Handle r = Handle Int
  deriving stock (Eq, Ord, Show)
  deriving newtype (Enum)

-- | The node id behind the handle, shared by every resource type.
handleId :: Handle r -> Int
handleId (Handle i) = i

{- | A handle with its resource type erased, for the introspection lists
that mix resource types ('Fragr.Snapshot.PassInfo', errors). Compares by node id:
ids are graph-global, so no two resources share one.
-}
data SomeHandle = forall r. SomeHandle (Handle r)

someHandleId :: SomeHandle -> Int
someHandleId (SomeHandle h) = handleId h

instance Eq SomeHandle where
  a == b = someHandleId a == someHandleId b

instance Ord SomeHandle where
  compare a b = compare (someHandleId a) (someHandleId b)

instance Show SomeHandle where
  showsPrec d (SomeHandle h) = showsPrec d h

{- |
Identifies a submission queue / timeline. The library never interprets it;
a backend maps it to (say) a Vulkan queue family and its timeline
semaphore. Passes default to 'defaultQueue' unless 'Fragr.Builder.setQueue' is called.
-}
newtype QueueId = QueueId Int
  deriving stock (Eq, Ord, Show)
  deriving newtype (Enum)

-- | The queue a pass runs on unless 'Fragr.Builder.setQueue' says otherwise.
defaultQueue :: QueueId
defaultQueue = QueueId 0

{- |
An ownership domain grouping queues ('Fragr.Compile.compileWith'): cross-queue
transfers are derived once per consuming family, and exclusively-owned
resources must not leave to two of them. Opaque to the library; a Vulkan
backend maps it to a queue family index.
-}
newtype FamilyId = FamilyId Int
  deriving stock (Eq, Ord, Show)
  deriving newtype (Enum)

{- |
Identifies a split-barrier event used to order two same-queue passes that
are /not/ adjacent (the producer signals the event after its pass, the
consumer waits on it before its pass). The library only mints and pairs
ids; the backend maps them to (say) @VkEvent@s.
-}
newtype EventId = EventId Int
  deriving stock (Eq, Ord, Show)
  deriving newtype (Enum)