Asynchronous data loader

This is the Asynchronous Loader. You can use it to load an image and use it, even if data are not yet available. You must specify a default loading image for using a such loader:

from kivy import *
image = Loader.image('mysprite.png')

You can also load image from url:

image = Loader.image('http://mysite.com/test.png')

If you want to change the default loading image, you can do:

Loader.loading_image = Image('another_loading.png')

Tweaking the asynchronous loader

New in version 1.6.0.

You can now tweak the loader to have a better user experience or more performance, depending of the images you’re gonna to load. Take a look at the parameters:

  • Loader.num_workers - define the number of threads to start for loading images
  • Loader.max_upload_per_frame - define the maximum image uploads in GPU to do per frames.
class kivy.loader.LoaderBase

Bases: object

Common base for Loader and specific implementation. By default, Loader will be the best available loader implementation.

The _update() function is called every 1 / 25.s or each frame if we have less than 25 FPS.

error_image

Image used for error. You can change it by doing:

Loader.error_image = 'error.png'

Changed in version 1.6.0: Not readonly anymore.

image(filename, load_callback=None, post_callback=None, **kwargs)

Load a image using loader. A Proxy image is returned with a loading image.

::
img = Loader.image(filename) # img will be a ProxyImage. # You’ll use it the same as an Image class. # Later, when the image is really loaded, # the loader will change the img.image property # to the new loaded image
loading_image

Image used for loading. You can change it by doing:

Loader.loading_image = 'loading.png'

Changed in version 1.6.0: Not readonly anymore.

max_upload_per_frame

Number of image to upload per frame. By default, we’ll upload only 2 images in the GPU per frame. If you are uploading many tiny images, you can easily increase this parameter to 10, or more. If you are loading multiples Full-HD images, the upload time can be consequent, and can stuck the application during the upload. If you want a smooth experience, let the default.

As matter of fact, a Full-HD RGB image will take ~6MB in memory, so it will take times. If you have activated mipmap=True too, then the GPU must calculate the mipmap of this big images too, in real time. Then it can be smart to reduce the max_upload_per_frame to 1 or 2. If you get ride of that (or reduce it a lot), take a look at the DDS format.

New in version 1.6.0.

num_workers

Number of workers to use while loading. (used only if the loader implementation support it.). This setting impact the loader only at the beginning. Once the loader is started, the setting has no impact:

from kivy.loader import Loader
Loader.num_workers = 4

The default value is 2 for giving a smooth user experience. You could increase the number of workers, then all the images will be loaded faster, but the user will not been able to use the application while loading. Prior to 1.6.0, the default number was 20, and loading many full-hd images was blocking completly the application.

New in version 1.6.0.

pause()

Pause the loader, can be useful during interactions

New in version 1.6.0.

resume()

Resume the loader, after a pause().

New in version 1.6.0.

run(*largs)

Main loop for the loader.

start()

Start the loader thread/process

stop()

Stop the loader thread/process

class kivy.loader.ProxyImage(arg, **kwargs)

Bases: kivy.core.image.Image

Image returned by the Loader.image() function.

Properties :
loaded: bool, default to False

It can be True if the image is already cached

Events :
on_load

Fired when the image is loaded and changed