Table Of Contents

• Asynchronous data loader
  • Tweaking the asynchronous loader
  • LoaderBase
    • LoaderBase.error_image
    • LoaderBase.image()
    • LoaderBase.loading_image
    • LoaderBase.max_upload_per_frame
    • LoaderBase.num_workers
    • LoaderBase.pause()
    • LoaderBase.resume()
    • LoaderBase.run()
    • LoaderBase.start()
    • LoaderBase.stop()
  • ProxyImage

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 when using the loader:

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

You can also load an image from a 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 tweak the loader to provide a better user experience or more performance, depending of the images you are going 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 frame.

class kivy.loader.LoaderBase

Bases: builtins.object

Common base for the Loader and specific implementations. By default, the 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.

property 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 the Loader. A ProxyImage is returned with a loading image. You can use it as follows:

from kivy.app import App
from kivy.uix.image import Image
from kivy.loader import Loader

class TestApp(App):
    def _image_loaded(self, proxyImage):
        if proxyImage.image.texture:
            self.image.texture = proxyImage.image.texture

    def build(self):
        proxyImage = Loader.image("myPic.jpg")
        proxyImage.bind(on_load=self._image_loaded)
        self.image = Image()
        return self.image

TestApp().run()

In order to cancel all background loading, call Loader.stop().

property 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.

property max_upload_per_frame

The number of images to upload per frame. By default, we’ll upload only 2 images to the GPU per frame. If you are uploading many small images, you can easily increase this parameter to 10 or more. If you are loading multiple full HD images, the upload time may have consequences and block the application. If you want a smooth experience, use the default.

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

New in version 1.6.0.

property num_workers

Number of workers to use while loading (used only if the loader implementation supports it). This setting impacts the loader only on initialization. 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 completely blocking 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, defaults to False

This value may be True if the image is already cached.

Events:

on_load

Fired when the image is loaded or changed.

on_error

Fired when the image cannot be loaded. error: Exception data that occurred

« Application

Atlas »