View Source Scenic.Assets.Stream (Scenic v0.11.2)
Manage streaming assets (for now only compressed images and bitmaps) that are available to all Scenes and ViewPorts.
The Scenic.Assets.Stream API gives to access to a running GenServer that manages an
:ets table and subscriptions to changes to named streams. This means that streaming
assets are available globally to all Scenes and ViewPorts.
You should be aware that if you have a GenServer that is rapidly updating a stream, but no scene's are listening, then you are doing unnecessary work. If you have only a single Scene in a single ViewPort listening to that stream, then create the stream in the scene.
If you have multiple Scenes listening to a stream, or the same stream in multiple ViewPorts, then create and update the stream in an independent GenServer that you manage outside of Scenic.
Link to this section Summary
Functions
Returns a specification to start this module under a supervisor.
Fully delete a named stream.
Check if a named stream has been published.
Check if a named stream has been published.
Fetch the currently published asset in a named stream.
Put a streamable asset into a named stream.
Same as put, but reverses the params order (making it pipe-able) and raises on failures.
Subscribe to changes in a named stream.
Unsubscribe to changes in a named stream.
Link to this section Types
@type asset() :: Scenic.Assets.Stream.Image.t() | Scenic.Assets.Stream.Bitmap.t()
@type id() :: String.t()
Link to this section Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec delete(id :: String.t()) :: :ok
Fully delete a named stream.
If you recreate the stream after deleting it, you can place any asset type into the new stream.
@spec exists!(id :: String.t()) :: :ok
Check if a named stream has been published.
Returns a :ok if the stream is published. Raises an error if it is not.
Check if a named stream has been published.
Returns a boolean indicating if the stream is published.
Fetch the currently published asset in a named stream.
Returns {:ok, asset} on success.
Returns {:error, :not_found} if the stream is not available.
Put a streamable asset into a named stream.
If the named stream does not exist yet, it is created. If it already exists, then it's content is updated with the asset.
Returns :ok on success.
Note: Once a stream is create, the asset being updated must be the same type as the asset that was originally created. I.e. you can't replace a Bitmap with an Image. This will make more sense in the future as other assets types (audio) become supported.
The contents of the asset is (lightly) validated as it is put into the :ets table.
If the content is invalid, or a different type than what is already in the stream,
then it returns {:error, :invalid, asset_type}.
Same as put, but reverses the params order (making it pipe-able) and raises on failures.
Returns the asset on success.
@spec subscribe(id :: String.t()) :: :ok
Subscribe to changes in a named stream.
Call this from a GenServer, typically a Driver or something you manage yourself.
When an asset stream is updated you will receive the following message.
{{Stream, :put}, stream_type, id}
You can match against stream_type to select certain kids of assets. Use the id to fetch the contents of the asset.
When an asset stream is deleted, you will receive the following message.
{{Stream, :delete}, stream_type, id}
You can subscribe to an stream before it has been published. You will then start receiving put messages when it is created. Your subscription will not end if the stream is deleted.
@spec unsubscribe(id :: String.t() | :all) :: :ok
Unsubscribe to changes in a named stream.
Once your process unsubscribes to a named stream, it will stop receiving all messages related to it