Hello World¶
Ahhh, the great tradition of saying “Hello World” in a programming language. To whet your appetite, we will do this with a most simple application, which will display an image. It is not important to understand everything at once, which will be used by the example. Nearly all parts used now are explained in later chapters, so do not hesitate, if the one or other explanation is missing.
Importing¶
Let’s start with importing some basic modules, which are necessary to display a small nice window and to do some basic drawing within that window.
import sys
import sdl2.ext
RESOURCES = sdl2.ext.Resources(__file__, "resources")
We need some resources from the resources
folder, so that we have a test
image around to display on the window later on. In your own applications, it is
unlikely that you will ever need to import them, but we need them here, so we
use the sdl2.ext.Resources
class to have them available.
Window creation and image loading¶
Any graphical application requires access to the screen, mostly in form of a window, which basically represents a portion of the screen, the application has access to and the application can manipulate. In most cases that portion has a border and title bar around it, allowing the user to move it around on the screen and reorganise everything in a way to fit his needs.
Once we have imported all necessary parts, let’s create a window to have access to the screen, so we can display the logo and thus represent it to the user.
sdl2.ext.init()
window = sdl2.ext.Window("Hello World!", size=(640, 480))
window.show()
factory = sdl2.ext.SpriteFactory(sdl2.ext.SOFTWARE)
sprite = factory.from_image(RESOURCES.get_path("hello.bmp"))
spriterenderer = factory.create_sprite_render_system(window)
spriterenderer.render(sprite)
First, we initialise the sdl2.ext
internals to gain access to the
screen and to be able to create windows on top of it. Once done with that,
sdl2.ext.Window
will create the window for us and we
supply a title to be shown on the window’s border along with its initial size.
Since sdl2.ext.Window
instances are not shown by default,
we have to tell the operating system and window manager that there is a new
window to display by calling sdl2.ext.Window.show()
.
Afterwards, we get an image from the resources folder and create a
sdl2.ext.Sprite
from it, which can be easily shown later
on. This is done via a sdl2.ext.SpriteFactory
, since the
factory allows us to switch between texture-based, hardware-accelerated, and
software-based sprites easily.
To display the image, we will use a sdl2.ext.SpriteRenderSystem
,
which supports the sprite type (texture- or software-based) and can copy the
image to the window for display. The sdl2.ext.SpriteRenderSystem
needs to know, where to copy to, thus we have to supply the window as target
for copy and display operations.
All left to do is to initiate the copy process by calling
sdl2.ext.SpriteRenderSystem.render()
with the image we
created earlier.
Tip
You will notice that the sprite used above will always be drawn at the
top-left corner of the sdl2.ext.Window
. You can change
the position of where to draw it by changing its
sdl2.ext.Sprite.position
value.
# will cause the renderer to draw the sprite 10px to the right and
# 20 px to the bottom
sprite.position = 10, 20
# will cause the renderer to draw the sprite 55px to the right and
# 10 px to the bottom
sprite.position = 55, 10
Experiment with different values to see their effect. Do not forget to do
this before spriterenderer.render(sprite)
is called.
Making the application responsive¶
We are nearly done now. We have an image to display, we have a window, where the image should be displayed on, so we can execute the written code, not?
Well, yes, but the only thing that will happen is that we will notice a short flickering before the application exits. Maybe we can even see the window with the image for a short moment, but that’s not what we want, do we?
To keep the window on the screen and to make it responsive to user input, such as closing the window, react upon the mouse cursor or key presses, we have to add a so-called event loop. The event loop will deal with certain types of actions happening on the window or while the window is focused by the user and - as long as the event loop is running - will keep the window shown on the screen.
processor = sdl2.ext.TestEventProcessor()
processor.run(window)
Since this is a very first tutorial, we keep things simple here and use a
dummy class for testing without actually dealing with the event loop magic.
By calling sdl2.ext.TestEventProcessor.run()
, we implicitly start an
event loop, which takes care of the most important parts for us.
And here it ends…¶
The window is shown, the image is shown, great! All left to do is to clean up
everything, once the application finishes. Luckily the
sdl2.ext.TestEventProcessor
knows when the window is closed, so
it will exit from the event loop. Once it exits, we should clean up the
video internals, we initialised at the beginning. Thus, a final call to
sdl2.ext.quit()
should be made.