DEV Community: code_egg

The Practical Guide to Game Development with Pygame---2. Understanding the Surface Object

code_egg — Mon, 12 Aug 2024 07:28:34 +0000

In the previous article, we used the pygame.display.set_mode() function to get a window object and the pygame.image.load() function to load an image, resulting in an image object. Both the window object and the image object are actually of the Surface type, and we collectively refer to them as Surface objects. The concept of Surface is crucial in Pygame, and this article will provide a detailed introduction.

Project code download link: https://github.com/la-vie-est-belle/pygame_codes

What is a Surface?

We can think of a Surface object in Pygame as a canvas. We can fill the canvas with colors or draw any images, text, and lines on it. Let’s briefly look at how to add images to various Surface objects. See Example Code 2-1.

import sys
import pygame

pygame.init()
surface1 = pygame.display.set_mode((800, 600))              # 1
pygame.display.set_caption('Surface Demo')

surface2 = pygame.image.load('pygame_logo.png')             # 2
surface2_rect = surface2.get_rect()
surface2_rect.center = (400, 300)

surface3 = pygame.image.load('python_logo.png')             # 3
surface3_rect = surface3.get_rect()
surface3_rect.topleft = (0, 0)

while True:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()
            sys.exit()

    surface1.fill((0, 255, 0), (0, 0, 400, 600))            # 4
    surface1.blit(surface2, surface2_rect)                  # 5

    surface2.blit(surface3, surface3_rect)                  # 6

    pygame.display.flip()

The result is as follows:

Code Explanation:

#1 Call the pygame.display.set_mode() function to get a Surface object that represents the screen.

#2 Call the pygame.image.load() function to load the Pygame logo, resulting in a Surface object the same size as the loaded image. The Rect object's center attribute is used to set the position of the Surface object. center specifies the center of the Surface, so this actually centers the Pygame logo on the screen.

#3 Similarly, load the Python logo image to get a Surface object the same size as this image. The top-left corner of its coordinates is set to (0, 0). Since the Python logo is to be added on top of the Pygame logo, (0, 0) positions the top-left corner of the Python logo at the origin of the Pygame logo's coordinate system.

Note: The coordinate system in Pygame will be explained in the next section.

#4 Use the fill() function of the Surface object to fill the left half of the window with green. This function can take a rectangular region to specify where to fill.

#5 Use the blit() function of the Surface object to draw another Surface object. Here, the Pygame logo Surface object is added to the window Surface object.

#6 Add the Python logo Surface object onto the Pygame logo Surface object.

Note: The Surface objects that are added later will obscure those added earlier.

How to Create a Surface

In Example Code 2-1, we obtained Surface objects using the pygame.display.set_mode() and pygame.image.load() functions. Additionally, we can create a Surface object directly using pygame.Surface() by specifying its width and height.

surface = pygame.Surface((1000, 800)) # Create a Surface object with a width of 1000 and height of 800

In Pygame, when we create text, we are essentially creating a Surface object where the text is rendered.

font = pygame.font.SysFont('Arial', 50)                 # Set the font
text = font.render('Hello pygame!', True, (0, 0, 0))    # Render the text; 'text' is a Surface object

Common Surface Functions

Here are some commonly used Surface object functions and properties.
1.

Surface.blit(source, dest, area=None)

The blit() function is used to draw one Surface object onto another. source is the source Surface object to be drawn, and dest is the target Surface object where the source will be drawn. The area parameter specifies the drawing region and defaults to None, meaning it will draw at the top-left corner with the width and height of the source Surface.

Surface.blits(((source, dest, area), ...))

The blits() function takes a sequence of tuples, each containing a source Surface, a destination Surface, and an optional area. This function allows drawing multiple Surface objects at once.

Surface.convert(Surface=None)
Surface.convert_alpha(Surface=None)

When you use pygame.image.load() to load an image and then draw it onto a target Surface using blit(), if the pixel format of the image does not match the pixel format of the target Surface, the blit() function performs an internal format conversion.

Since blit() is called every frame, performing format conversion every time can be performance-intensive. Therefore, you can call convert() to convert the pixel format of the image to match the screen Surface format when loading the image. If no Surface parameter is specified, it defaults to converting to the format of the screen Surface. For example:

surface1 = pygame.image.load('demo.jpg').convert()
surface3 = pygame.image.load('demo.png').convert_alpha()

If the image has transparency, use convert_alpha() to preserve the image's transparency effects.

Note: Pixel format refers to the way pixel data is stored, including color channel arrangement and bit depth, not the file format (.jpg, .png, .gif).

Surface.copy()

Creates a copy of a Surface object. The copied Surface has the same pixel format as the original.

Surface.fill(color, rect=None)

Fills the target Surface object with a color. The rect parameter specifies the region to fill; if not provided, the entire Surface is filled.

Surface.get_size()

Gets the width and height of the Surface object in pixels, returning a tuple (width, height).

Surface.get_width()

Gets the width of the Surface object in pixels.

Surface.get_height()

Gets the height of the Surface object in pixels.

Surface.get_rect()

Gets the rectangle area of the Surface object, returning a Rect object.

In Example Code 2-2, we will demonstrate the use of these functions.

import sys
import pygame

pygame.init()
screen = pygame.display.set_mode((800, 600))
pygame.display.set_caption('Surface Demo')

pygame_logo = pygame.image.load('pygame_logo.png').convert_alpha()  # 1
pygame_logo_rect = pygame_logo.get_rect()
pygame_logo_rect.center = (400, 300)
print(pygame_logo.get_size())                                       # 2
print(pygame_logo.get_width())
print(pygame_logo.get_height())

python_logo = pygame.image.load('python_logo.png').convert_alpha()
python_logo_rect = python_logo.get_rect()
python_logo_rect.topleft = (0, 0)
print(python_logo.get_size())
print(python_logo.get_width())
print(python_logo.get_height())

python_logo2 = python_logo.copy()                                   # 3
python_logo_rect2 = python_logo.get_rect()
python_logo_rect2.topright = (600, 100)
print(python_logo2.get_size())
print(python_logo2.get_width())
print(python_logo2.get_height())

while True:
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()
            sys.exit()

    screen.fill((0, 255, 0), (0, 0, 400, 600))
    screen.blit(pygame_logo, pygame_logo_rect)

    pygame_logo.blits(((python_logo, python_logo_rect), (python_logo2, python_logo_rect2)))     # 4

    pygame.display.flip()

The result is as follows:

Code Explanation:
#1 Call the convert_alpha() function to convert the image's pixel format and retain its transparency.

#2 Use get_size(), get_width(), and get_height() functions to obtain the dimensions of the Surface object.

#3 Use the copy() function to create a copy of a Surface object and set its top-right corner to (600, 100).

#4 Use the blits() function to draw two Python logo images onto the Pygame logo. As observed, part of the Python logo on the right is not displayed because it is outside the rectangle area of the Pygame logo, so it is not rendered.

Summary

In this article, we introduced the Surface, including its concept, creation methods, and common functions, and demonstrated their usage with examples. The Surface is a key concept in Pygame, and understanding it will enhance your familiarity with Pygame.

Buy author a cup of coffee if you enjoyed this tutorial. :)

The Practical Guide to Game Development with Pygame---1. Introduction to Pygame

code_egg — Sat, 10 Aug 2024 05:42:40 +0000

In this article, we will learn how to download and install the Pygame, a game development library, and we will run a simple sample project to get acquainted with Pygame.

Project code download link: https://github.com/la-vie-est-belle/pygame_codes

Installing Pygame

Installing Pygame on Windows
Open a command line window and type the command pip install pygame followed by pressing Enter. If you see the message Successfully installed pygame at the end, it means that Pygame has been successfully installed.

Note: The version of Pygame used in this tutorial is 2.6.0.

Of course, we also need to verify if Pygame is working correctly. Open the command line window, type python, and press Enter to enter the Python command line interface. Then type import pygame. If the Pygame welcome message appears, it means the installation is successful and Pygame can be used normally.

Installing Pygame on MacOS
Similarly, open a terminal, type pip3 install pygame, and press Enter to install Pygame. The verification method is the same as above, and will not be repeated here.

Running a Pygame Sample Project

Open a command line window and run the command python -m pygame.examples.aliens to start the built-in alien game that comes with Pygame. The controls are as follows:

Arrow keys to move the player
Spacebar to shoot

In the upcoming practical articles, we will develop and implement this alien game together. For now, let’s take a look at this simple Pygame example code 1-1.

import sys
import pygame

pygame.init()                                       # 1
screen = pygame.display.set_mode((1100, 600))       # 2
pygame.display.set_caption('Dino Runner')           # 3

icon = pygame.image.load('icon.png')                # 4
pygame.display.set_icon(icon)

dino = pygame.image.load('dino_start.png')          # 5
dino_rect = dino.get_rect()
dino_rect.topleft = (80, 300)

while True:                                         # 6
    for event in pygame.event.get():                # 7
        if event.type == pygame.QUIT:
            pygame.quit()
            sys.exit()

    screen.fill((255, 255, 255))                    # 8
    screen.blit(dino, dino_rect)                    # 9
    pygame.display.flip()                           # 10

The result is as follows:

Code Explanation:
#1 pygame.init() initializes all the modules in the Pygame library. This line must be included before using any Pygame functions or classes.

#2 Call the pygame.display.set_mode() function to set the size of the game window (size is passed as a tuple). This function returns a window object, which is stored in the variable screen. This object allows you to draw graphics, add images, and text to the window. The pygame.display module is dedicated to window management and screen display.

#3 Use the pygame.display.set_caption() function to set the window title.

#4 Use the pygame.image.load() function to load an image, in this case, the window icon. This function returns an image object, which is stored in the icon variable. Next, use the pygame.display.set_icon() function to set the window icon.

#5 Load the main character image, and call get_rect() to obtain the rectangle area of the character image (a Rect object), and set the top-left corner topleft of this rectangle to the screen position.

Note: The origin of the screen coordinates is at the top-left corner, with the X-axis extending to the right and the Y-axis extending downward. The coordinate system in Pygame will be explained in detail in later chapters.

#6 Enter a game loop where Pygame will continuously detect and handle user input, update game states, or update screen contents.

#7 Use pygame.event.get() to get an event queue. In the for loop, we read and handle each event. If the event type event.type is pygame.QUIT (i.e., closing the window), call pygame.quit() to exit the game. sys.exit() terminates the current Python program, cleans up, and exits the thread running the Pygame program.

#8 Call the fill() function of the window object screen to fill the window with a color. You pass a tuple representing the color's RGB values, in this case, white.

#9 Call the blit() function of the window object screen to display the character image on the screen, with the position defined by the previously set rectangle dino_rect. You can also pass a coordinate tuple (x, y) to blit() to set the character's position on the screen, such as:

screen.blit(dino, (80, 300))

#10 Call the pygame.display.flip() function to refresh the screen content. You can also use pygame.display.update() to achieve the same effect. The latter can also accept a rectangle area to update only that portion of the screen. For example, the following line will update only a rectangle with the top-left corner at (0, 0) and a width and height of 350 pixels.

pygame.display.update((0, 0, 350, 350))

Summary

In this article, we learned how to install Pygame on Windows and MacOS, and explored a simple example code to understand the basic structure, operation principles, and some common functions of Pygame. If there are any parts that you do not fully understand, you can leave them for now. Later chapters may help clarify these concepts.

Buy author a cup of coffee if you enjoyed this tutorial. :)