2D drawing
Prev   Next

2D drawing

The ocempgui.draw module contains several wrapper functions around various pygame drawing functions, which are used by the ocempgui.widgets module. It is divided in several submodules, of which each one contains various related functions such as creating rectangle surfaces, drawing strings or loading images. Although not any function defined within the ocempgui.draw module simplifies the usage of the pygame drawing functions, they can reduce the amount of code to write and several of them enable you to simplify specific operations.

To use the drawing routines in your own code, you can simply import the module using: 

import ocempgui.draw

Geometric objects

The ocempgui.draw.Draw submodule contains several functions for geometric objects. Although most of them are only wrappers around the respective pygame functions, some of them can be used to create more complex geometric objects. The following list gives an overview about the functions defined within this submodule.

draw_line (surface, color, a, b, width=1)

Draws a line with the given width from a to b on the passed surface. This function simply wraps the pygame.draw.line() function.

You can find the following example as a python script under examples/draw_line.py. 

# Draw.draw_line () usage example.
import pygame, pygame.locals
from ocempgui.draw import Draw

# Initialize the drawing window.
pygame.init ()
screen = pygame.display.set_mode ((200, 200))
screen.fill ((250, 250, 250))
pygame.display.set_caption ('Draw.draw_line ()')

# Draw horizontal lines in different colors and sizes.
for i in range (10):
    val = i * 10
    Draw.draw_line (screen, (0 + val, 50 + val, 40 + 2 * val),
                    (5, val), (195, val), i)

# Draw vertical lines in different colors and sizes.
for i in range (10):
    val = i * 8
    Draw.draw_line (screen, (0 + 2 * val, 30 + val, 35 + 2 * val),
                    (5 + i * 10, 100), (5 + i * 10, 195), i)

# Draw a cross.
Draw.draw_line (screen, (0, 0, 0), (120, 100), (195, 195), 3)
Draw.draw_line (screen, (0, 0, 0), (195, 100), (120, 195), 3)

# Show anything.
pygame.display.flip ()

# Wait for input.
while not pygame.event.get ([pygame.locals.QUIT]):
    pass

Example 2. Draw.draw_line ()


draw_rect (width, height,color=None)

Creates a rectangle surface with a size of width and height, which can be manipulated and blitted on other surfaces. This function simply wraps the pygame.Surface function and calls Surface.fill() on demand.

You can find the following example as a python script under examples/draw_rect.py. 

# Draw.draw_rect () usage example.
import random
import pygame, pygame.locals
from ocempgui.draw import Draw

# Initialize the drawing window.
pygame.init ()
screen = pygame.display.set_mode ((200, 200))
screen.fill ((250, 250, 250))
pygame.display.set_caption ('Draw.draw_rect ()')

# Draw rectangles with various colors.
rect = Draw.draw_rect (55, 40, (255, 0, 0))
screen.blit (rect, (5, 5))

rect = Draw.draw_rect (55, 40, (0, 255, 0))
screen.blit (rect, (65, 5))

rect = Draw.draw_rect (55, 40, (0, 0, 255))
screen.blit (rect, (125, 5))

# Draw encapsulated rectangles.
for i in range (30):
    val = i + 3
    rnd = (random.randint (0, 5), random.randint (0, 5), random.randint (0, 5))
    color = (rnd[0] * i + 100,  rnd[1] * i + 100, rnd[2] * i + 100)
    rect = Draw.draw_rect (100 - 2 * val, 100 - 2 * val, color)
    screen.blit (rect, (5 + val, 50 + val))

# Show anything.
pygame.display.flip ()

# Wait for input.
while not pygame.event.get ([pygame.locals.QUIT]):
    pass

Example 3. Draw.draw_rect ()


draw_triangle (surface, color, a, b, c, width=0)

Draws a triangle using the vertices a, b and c on the passed surface. This function simply wraps the pygame.draw.polygon() function.

You can find the following example as a python script under examples/draw_triangle.py. 

# Draw.draw_triangle () usage example.
import pygame, pygame.locals
from ocempgui.draw import Draw

# Initialize the drawing window.
pygame.init ()
screen = pygame.display.set_mode ((200, 200))
screen.fill ((250, 250, 250))
pygame.display.set_caption ('Draw.draw_triangle ()')

# Draw three triangles.
Draw.draw_triangle (screen, (255, 0, 0), (20, 5), (5, 30), (35, 30), 0)
Draw.draw_triangle (screen, (0, 255, 0), (25, 5), (40, 30), (55, 5), 0)
Draw.draw_triangle (screen, (0, 0, 255), (60, 5), (45, 30), (75, 30), 0)

# Draw a 'tunnel effect' of triangles.
for i in range (30):
     val = i + 3
     color = (val * 4, val * 7, val * 5)
     Draw.draw_triangle (screen, color, (5 + 2 * val, 50 + val),
                         (195 - 2 * val, 50 + val), (100, 195 - 2 * val), 1)

# Show anything.
pygame.display.flip ()

# Wait for input.
while not pygame.event.get ([pygame.locals.QUIT]):
    pass

Example 4. Draw.draw_triangle ()


Image manipulation

The ocempgui.draw.Image submodule contains image related functions, such as loading or saving image data.

load_image (filename, alpha=False, colorkey=None)

Loads an image from the specified filename and automatically converts it to the current display pixel format. If alpha is set to True, the method will try enable alpha transparency by using the pygame.Surface.convert_alpha() method. If the colorkey argument is set to a color value, the method tries to add color based transparency using the pygame.Surface.set_colorkey() method. This function is just a wrapper around pygame.image.load() and additionally calls Surface.convert().

You can find the following example as a python script under examples/load_image.py. 

# Image.load_image () usage example.
import pygame, pygame.locals
from ocempgui.draw import Image

# Initialize the drawing window.
pygame.init ()
screen = pygame.display.set_mode ((120, 100))
screen.fill ((250, 250, 250))
pygame.display.set_caption ('Image.load_image ()')

# Load an image and blit it on the screen.
image = Image.load_image ("./image.png")
screen.blit (image, (10, 10))

# Show anything.
pygame.display.flip ()

# Wait for input.
while not pygame.event.get ([pygame.locals.QUIT]):
    pass

Example 5. Image.load_image ()


Text rendering

The ocempgui.draw.String submodule contains functions, which allow the creation and manipulation of fonts and string surfaces. It includes a simple font caching system, which provides a fast availability of fonts, which were created earlier. Besides this feature, the string surface related functions are mostly wrappers around the respective pygame functions.

create_font (fontfile, size, style)

Creates and returns a pygame.Font object from the given fontfile using the passed size and style. The font will be cached internally, so that a second invocation using the same fontfile and size will return the cached font.

Note

If you manipulate the returned pygame.Font directly, the manipulation will be applied to the cached font, too. To circumvent this behaviour, create a copy of the return value using the pygame.Font.copy() method and manipulate the copy.

You can find the following example as a python script under examples/create_font.py. 

# String.create_font () usage example.
import pygame
from ocempgui.draw import String

def check (font, name):
    bold = "not bold"
    if font.get_bold ():
        bold = "bold"
    print "%s at %s is %s" % (name, font, bold)

# Initialize the pygame engine.
pygame.init ()

# Create a font from the ttf located in the current directory.
font = String.create_font ("tuffy.ttf", 14)
check (font, "font")

# Now create a second font and manipulate it.
# NOTE: Due to the caching we are using the same font object as above!
font_mod = String.create_font ("tuffy.ttf", 14)
font_mod.set_bold (True)

# Output the bold state of both fonts.
check (font, "font")
check (font_mod, "font_mod")

Example 6. String.create_font ()


create_system_font (fontname, size, style)

Creates and returns a pygame.Font object from the given system font with the specified fontname and the given size and style. Like the create_font() function, the font will be cached internally, so that a second invocation with the same parameters will return the cached font.

Note

If you manipulate the returned pygame.Font directly, the manipulation will be applied to the cached font, too. To circumvent this behaviour, create a copy of the return value using the pygame.Font.copy() method and manipulate the copy.

The pygame.SysFont documentation also notes this:

 

This will always return a valid Font object, and will fallback on the builtin pygame font if the given font is not found.

 
 --Pygame documentation

You can find the following example as a python script under examples/create_system_font.py. 

# String.create_system_font () usage example.
import pygame
from ocempgui.draw import String

# Initialize the pygame engine.
pygame.init ()

# Create some fonts.
fonts = {}
names = ( "Arial", "Helvetica", "Sans", "Serif", "Times" )
for name in names:
    fonts[name] = String.create_system_font (name, 14)

# Output the fonts as well as their object address.
for name in fonts:
    print "Loaded: %s at %s" % (name, fonts[name])

Example 7. String.create_system_font ()


draw_string (text, font, size, antialias, color, style)

Creates a transparent surface displaying the text in the given color with the specified style applied. If antialias evaluates to True, the text will be rendered using antialiasing (if possible).

Note

The function first tries to resolve font as font file. If that fails, it looks for a system font name, which matches the font name and returns a Font object based on those information (or the fallback font of pygame, see also create_system_font (fontname, size, style) .

You can find the following example as a python script under examples/draw_string.py. 

# String.draw_string () usage example.
import pygame, pygame.locals
from ocempgui.draw import String

# Initialize the drawing window.
pygame.init ()
screen = pygame.display.set_mode ((400, 100))
screen.fill ((250, 250, 250))
pygame.display.set_caption ('String.draw_string ()')

# Create a text using the ttf located in the current directory.
text = String.draw_string ("This is tuffy.ttf", "tuffy.ttf", 16, 1, (0, 0, 0))
screen.blit (text, (5, 5))

# Create a text using the 'Times' system font
text = String.draw_string ("This is Times", "Times", 16, 1, (255, 0, 0))
screen.blit (text, (5, 35))

# Create a text using the fallback python font by specifying a wrong
# font name (hopefully ;-).
text = String.draw_string ("This is the fallback", "invalid_font_name_here",
                           16, 1, (0, 0, 255))
screen.blit (text, (5, 60))

# Now the same again without antialiasing.
text = String.draw_string ("This is tuffy.ttf (no aa)", "tuffy.ttf",
                           16, 0, (0, 0, 0))
screen.blit (text, (200, 5))

text = String.draw_string ("This is Times (no aa)", "Times",
                           16, 0, (255, 0, 0))
screen.blit (text, (200, 35))

text = String.draw_string ("This is the fallback (no aa)",
                           "invalid_font_name_here", 16, 1, (0, 0, 255))
screen.blit (text, (200, 60))

# Show anything.
pygame.display.flip ()

# Wait for input.
while not pygame.event.get ([pygame.locals.QUIT]):
    pass

Example 8. String.draw_string ()


draw_string_with_bg (text, font, size, antialias, color, bgcolor, style)

This function is identical to the draw_string (text, font, size, antialias, color, style) function, except that it provides a background color via the bgcolor parameter.

You can find the following example as a python script under examples/draw_string_with_bg.py. 

# String.draw_string_with_bg () usage example.
import pygame, pygame.locals
from ocempgui.draw import String

# Initialize the drawing window.
pygame.init ()
screen = pygame.display.set_mode ((100, 100))
screen.fill ((250, 250, 250))
pygame.display.set_caption ('String.draw_string_with_bg ()')

# Create texts using the 'Times' system font and different background
# colors.
text = String.draw_string_with_bg ("This is Times", "Times", 16, 1, (0, 0, 0),
                                   (200, 200, 200))
screen.blit (text, (5, 5))

text = String.draw_string_with_bg ("This is Times", "Times", 16, 1, (0, 0, 0),
                                   (0, 200, 0))
screen.blit (text, (5, 60))

# Show anything.
pygame.display.flip ()

# Wait for input.
while not pygame.event.get ([pygame.locals.QUIT]):
    pass

Example 9. String.draw_string_with_bg ()


Complex objects

The ocempgui.draw.Complex module contains more advanced drawing objects, that implement interesting features for 2D graphics.

The FaderSurface class enhances the pygame.Surface class by some additional attributes and methods to support fade-in/fade-out operations. You can adjust them to fit its behaviour to your needs, such as setting the current transparency value using the alpha attribute 

surface.alpha = 0 # Make it completely transparent
or adjusting the step range for in- or decrements upon each update. 
surface.step = 5

You can find the following example as a python script under examples/fader_surface.py. 

# Complex.FaderSurface usage example.
import pygame, pygame.locals
from ocempgui.draw import Complex, Image

# Initialize the drawing window.
pygame.init ()
screen = pygame.display.set_mode ((120, 100))
screen.fill ((180, 180, 180))
pygame.display.set_caption ('Complex.FaderSurface')

# Create a surface we can use to display.
image = Image.load_image ("./image.png")
r = image.get_rect ()

# Create a new FaderSurface with the same dimensions and an initial
# transparency of 1.
surface = Complex.FaderSurface (r.width, r.height, 1)

# Blit the original on the FaderSurface.
surface.blit (image, (0, 0))

# The default step value is -1, but we want to fade the image in.
surface.step = 1

# Loop until the FaderSurface reached the maximum or minimum alpha
# transparency value.
while surface.update ():

    # Clean up and blit the surface..
    screen.fill ((180, 180, 180))
    screen.blit (surface, (10, 10))
    pygame.display.flip ()

    # Check the bounds. We have to check the maximum values - 1, because
    # 255 and 0 cause the surface to return False and we would exit the
    # loop.
    if surface.alpha == 254 or surface.alpha == 1:
        surface.step = -surface.step

    pygame.time.delay (50 / 4)
    
    # Wait for input.
    if pygame.event.get ([pygame.locals.QUIT]):
        break

Example 10. FaderSurface example


Prev   Next
Implementing accessibility Home Tracking object states - the observer pattern