TSdlApp
Entry point class for all SDL applications. You must override this class and its methods where appropriate.
Definition
Unit: Neslib.Sdl3
Inheritance
Properties
| Name | Description |
|---|---|
| ErrorMessage | The last SDL error message. It is possible for multiple errors to occur checking this property. |
| HasError | Whether an SDL API returned an error. |
| Instance | The singleton application instance. |
Constructors
| Name | Description |
|---|---|
| Create | |
| Destroy |
Methods
| Name | Description |
|---|---|
| Event | This method is called as needed by SDL after the Init method returns TSdlAppResult.Continue. It is called once for each new event. |
| HandleError | This method is called when an SDL API returned an error. It is called from the thread that caused the error. |
| Init | This method is called by SDL once, at startup. The method should initialize whatever is necessary, possibly create windows and open audio devices, etc. |
| Iterate | This method is called repeatedly by SDL after the Init method returns TSdlAppResult.Continue. The method should operate as a single iteration the program's primary loop; it should update whatever state it needs and draw a new frame of video, usually. |
| Quit | This method is called once by SDL before terminating the program. |
Property Descriptions
ErrorMessage
The last SDL error message. It is possible for multiple errors to occur checking this property.
You usually only need to use this property if you override HandleError and decide not to raise an exception. In that case, you can use HasError to check if an error has occurred, and if so, use this property to retrieve the error message.
Reading this property will not clear the error message. You need to use HasError at a later point again to check for errors.
class property ErrorMessage: String read GetErrorMessage
Type: String
See Also
Remarks
This property will return the error message that was specific to the thread that caused it.
HasError
Whether an SDL API returned an error.
You usually only need to use this property if you override HandleError and decide not to raise an exception. In that case, you can use this property to check if an error has occurred.
It doesn't tell you what API caused the error, just that any SDL API that was used since the last check of this property caused an error. It will only be reset to False once this property has been read.
class property HasError: Boolean read GetHasError write FHasError
Type: Boolean
See Also
Remarks
This property is not specific to the thread that caused the error. Any thread that causes an error will set this global property.
Instance
The singleton application instance.
class property Instance: TSdlApp read FInstance
Type: TSdlApp
Constructor Descriptions
Create
constructor Create
Destroy
destructor Destroy; override
Method Descriptions
Event(TSdlEvent)
This method is called as needed by SDL after the Init method returns TSdlAppResult.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 queue will trigger this method. SDL is responsible for pumping the event queue between each call to Iterate, so in normal operation one should only get events in a serial fashion, but be careful if you have a thread that explicitly calls TSdlEvents.Push. SDL itself will push events to the queue on the main thread.
Events sent to this method are not owned by the app; if you need to save the data, you should copy it.
This method should not go into an infinite mainloop; it should handle the provided event appropriately and return.
If this method returns TSdlAppResult.Continue, the app will continue normal operation, receiving repeated calls to Iterate and Event for the life of the program. If this method returns TSdlAppResult.Failure, SDL will call Quit and terminate the process with an exit code that reports an error to the platform. If it returns TSdlAppResult.Success, SDL calls Quit and terminates with an exit code that reports success to the platform.
By default this method returns TSdlAppResult.Continue, unless a Quit event is received, in which case it returns TSdlAppResult.Success.
function Event(const AEvent: TSdlEvent): TSdlAppResult; virtual
Parameters
AEvent: TSdlEvent
: The new event for the app to examine.
Returns
TSdlAppResult: Your should return TSdlAppResult.Failure to terminate with an error, TSdlAppResult.Success to terminate with success or TSdlAppResult.Continue to continue.
Remarks
This method may get called concurrently with Iterate or Quit for events not pushed from the main thread.
HandleError(String)
This method is called when an SDL API returned an error. It is called from the thread that caused the error.
By default, this method raises an exception of type ESdlError, but you can override this method perform some other action, such as logging the error instead. However, if you choose to not raise an exception, then the flow of execution will not be interrupted and you will have to use HasError and ErrorMessage to check for errors. Also, when the construction of an object (eg. a Texture, Window, Audio stream etc.) fails, and an exception is not raised, then you will have to check if the object is not nil before using it.
procedure HandleError(const AMessage: String); virtual
Parameters
AMessage: String
: The error message.
See Also
Remarks
This method is called from the thread that caused the error.
Init
This method is called by SDL once, at startup. The method should initialize whatever is necessary, possibly create windows and open audio devices, etc.
This method should not go into an infinite mainloop; it should do any one-time setup it requires and then return.
If this method returns TSdlAppResult.Continue, the app will proceed to normal operation, and will begin receiving repeated calls to the Iterate and Event methods for the life of the program. If this method returns TSdlAppResult.Failure, SDL will call the Quit method and terminate the process with an exit code that reports an error to the platform. If it returns TSdlAppResult.Success, SDL calls the Quit method and terminates with an exit code that reports success to the platform.
This method is called by SDL on the main thread.
Can be overridden to initialize the application, for example to create a window and renderer.
By default this method just returns TSdlAppResult.Continue.
function Init: TSdlAppResult; virtual
Returns
TSdlAppResult: Your should return TSdlAppResult.Failure to terminate with an error, TSdlAppResult.Success to terminate with success or TSdlAppResult.Continue to continue.
Iterate
This method is called repeatedly by SDL after the Init method returns TSdlAppResult.Continue. The method should operate as a single iteration the program'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 life of your app!). There are no promises made about what frequency this function might run at. You should use SDL's timer functions if you need to see how much time has passed since the last iteration.
There is no need to process the SDL event queue during this method; SDL will send events as they arrive in the Event method, and in most cases the event queue will be empty when this method runs anyhow.
This method should not go into an infinite mainloop; it should do one iteration of whatever the program does and return.
If this method returns TSdlAppResult.Continue, the app will continue normal operation, receiving repeated calls to Iterate and Event for the life of the program. If this method returns TSdlAppResult.Failure, SDL will call Quit and terminate the process with an exit code that reports an error to the platform. If it returns TSdlAppResult.Success, SDL calls Quit and terminates with an exit code that reports success to the platform.
This method is called by SDL on the main thread.
By default this method just returns TSdlAppResult.Continue.
function Iterate: TSdlAppResult; virtual
Returns
TSdlAppResult: Your should return TSdlAppResult.Failure to terminate with an error, TSdlAppResult.Success to terminate with success or TSdlAppResult.Continue to continue.
Remarks
This method may get called concurrently with the Event method for events not pushed on the main thread.
Quit(TSdlAppResult)
This method is called once by SDL before terminating the program.
This method will be called no matter what, even if the Init method requests termination.
This method should not go into an infinite mainloop; it should deinitialize any resources necessary, perform whatever shutdown activities, and return.
You do not need to call SdlQuit in this method, as SDL will call it after this method returns and before the process terminates, but it is safe to do so.
This method is called by SDL on the main thread.
Does nothing by default.
procedure Quit(const AResult: TSdlAppResult); virtual
Parameters
AResult: TSdlAppResult
: the result code that terminated the app (success or failure).
Remarks
The Event method may get called concurrently with this method if other threads that push events are still active.