Class AppBase
- Namespace
- Sdl3Sharp
- Assembly
- Sdl3Sharp.dll
A base class for an app's lifetime model
public abstract class AppBase- Inheritance
-
AppBase
- Inherited Members
Properties
Continue
Gets Continue. This is thought of as a convenient shorthand property for Continue used by types extending from AppBase.
protected static AppResult Continue { get; }Property Value
Failure
Gets Failure. This is thought of as a convenient shorthand property for Failure used by types extending from AppBase.
protected static AppResult Failure { get; }Property Value
Success
Gets Success. This is thought of as a convenient shorthand property for Success used by types extending from AppBase.
protected static AppResult Success { get; }Property Value
Methods
OnEvent(Sdl, ref Event)
The event handling entry point for an AppBase's execution
protected virtual AppResult OnEvent(Sdl sdl, ref Event @event)Parameters
Returns
Remarks
This method is called as needed after OnInitialize(Sdl, string[]) returned Continue. It is called once for each new event.
There is (currently) no guarantee about what thread this will be called from; whatever thread pushes an event onto SDL's event queue will trigger a call to this method. SDL is responsible for pumping the event queue between each call to OnIterate(Sdl), so in normal operation one should only get events in a serial fashion, but be careful if you have a thread that explicitly calls TryPushEvent(in Event). SDL itself will push events to the queue on the main thread.
Events sent to this method by reference are not owned (by you), nor are those references required to be alive after the call to this method; if you need to save the data, you should copy it!
This method should not go into an infinite loop; it should handle the provided event appropriately and return.
If this method returns Continue, the AppBase's execution will continue normal operation, receiving repeated calls to OnIterateInternal(Sdl) and OnEvent(Sdl, ref Event) for the execution time of the AppBase. If this method returns Failure, OnQuit(Sdl, AppResult) will be called and terminate the AppBase's execution with a return value that can be used as an exit code for program that reports an error to the platform. If it returns Success, OnQuit(Sdl, AppResult) will be called and terminate the AppBase's execution with a return value that can be used as an exit code for the program that reports success to the platform.
This method may get called concurrently with OnIterate(Sdl) or OnQuit(Sdl, AppResult) for events not pushed from the main thread.
OnInitialize(Sdl, string[])
The initial entry point for an AppBase's execution
protected virtual AppResult OnInitialize(Sdl sdl, string[] args)Parameters
sdlSdlargsstring[]A further processed collection of arguments passed from Run(AppBase, ReadOnlySpan<string>) or Run<TArguments>(AppBase, in TArguments?)
Returns
Remarks
This method is called once, at the start of the AppBase's execution. It should initialize whatever is necessary, possibly create windows and open audio devices, etc.
This method should not go into an infinite loop; it should do any one-time setup it requires and then return.
The args parameter contains almost the same collection of arguments as the caller passed to Run(AppBase, ReadOnlySpan<string>) or Run<TArguments>(AppBase, in TArguments?).
But notice that SDL does further (sometimes platform depended) processing on those arguments between the calls to those methods and the call to this method.
You should treat those arguments as you normally would main entry point arguments.
If this method returns Continue, the AppBase's execution will proceed to normal operation, and will begin receiving repeated calls to OnIterateInternal(Sdl) and OnEvent(Sdl, ref Event) for the execution time of the AppBase. If this method returns Failure, OnQuit(Sdl, AppResult) will be called immediately and terminate the AppBase's execution with a return value that can be used as an exit code for program that reports an error to the platform. If it returns Success, OnQuit(Sdl, AppResult) will be called immediately and terminate the AppBase's execution with a return value that can be used as an exit code for the program that reports success to the platform.
This method is called by SDL on the main thread.
OnIterate(Sdl)
The iteration entry point for an AppBase's execution
protected virtual AppResult OnIterate(Sdl sdl)Parameters
Returns
Remarks
This method is called repeatedly after OnInitialize(Sdl, string[]) returned Continue. The method should operate as a single iteration the AppBase's primary loop; it should update whatever state it needs and draw a new frame of video, usually.
On some platforms, this method will be called at the refresh rate of the display (which might change during the lifetime of your app!). There are no promises made about what frequency this method might run at. You should use the Timer functionality (e.g. MillisecondTicks) if you need to see how much time has passed since the last iteration.
There is no need to process events during this method; events will be send to OnEvent(Sdl, ref Event) as they arrive, and in most cases the event queue will be empty when this method runs anyhow.
This method should not go into an infinite loop; it should do one iteration of whatever it needs to do and return.
If this method returns Continue, the AppBase's execution will continue normal operation, receiving repeated calls to OnIterateInternal(Sdl) and OnEvent(Sdl, ref Event) for the execution time of the AppBase. If this method returns Failure, OnQuit(Sdl, AppResult) will be called immediately and terminate the AppBase's execution with a return value that can be used as an exit code for program that reports an error to the platform. If it returns Success, OnQuit(Sdl, AppResult) will be called immediately and terminate the AppBase's execution with a return value that can be used as an exit code for the program that reports success to the platform.
This method is called by SDL on the main thread.
OnQuit(Sdl, AppResult)
The deinitialising entry point for an AppBase's execution
protected virtual void OnQuit(Sdl sdl, AppResult result)Parameters
sdlSdlresultAppResultThe AppResult that terminated the execution of this AppBase (Success or Failure)
Remarks
This method is called once before terminating the execution of the AppBase.
This method will be called no matter what, even if OnInitialize(Sdl, string[]) requests termination.
This method should not go into an infinite loop; it should deinitialize any resources necessary, perform whatever shutdown activities, and return.
You do not need to dispose the sdl instance in this method, as that will be done automatically it after this method returns,
but it is safe to do so (with an exception regarding concurrent calls to OnEvent(Sdl, ref Event) which might receive the disposed Sdl instance by then).
The sdl instance is disposed after the call to this method no matter what. This is unavoidable!
This method is called by SDL on the main thread, though OnEvent(Sdl, ref Event) may get called concurrently with this method if other threads that push events are still active.