fsleyes.gl.resources

This module implements a simple API for managing shared OpenGL resources. Some OpenGL resources (e.g. textures) take up a lot of memory so it makes sense to share these resources where possible, instead of creating and maintaining multiple copies. The API defined in this module consists of the following functions:

exists

Returns True if a resource with the specified key exists, False otherwise.

get

Return a reference to the resource wiuh the specified key.

set

Create a new resource, or update an existing one.

delete

Decrements the reference count of the resource with the specified key.

On creation, resources must be given a unique name, referred to as a key. Subsequent accesses to the resource are performed by specifying this key. As an example, let’s say that we have a Image called myImage:

import fsleyes.gl.resources as glresources
import fsleyes.gl.textures  as gltextures
import fsl.data.image       as fslimage

image = fslimage.Image('data.nii.gz')

We wish to create an ImageTexture which can be shared by multiple users. All users of this texture can use the get() function to access the texture. The first call to get() will result in the texture being created, whereas subsequent calls will return a reference to the existing texture, and will increase its reference count:

texture = glresources.get(
    'myTexture',
     gltextures.ImageTexture,
     'myTexture',
     image,
     interp=gl.GL_LINEAR)

Note

Here, we have used 'myTexture' as the resource key. In practice, you will need to use something that is guaranteed to be unique throughout your application.

When a user of the texture no longer needs the texture, it must call the delete() method. Calls to delete() will decrement the reference count; when this count reaches zero, the texture will be destroyed:

glresources.delete('myTexture')

Note

This module was written for managing OpenGL Texture objects, but can actually be used with any type - the only requirement is that the type defines a method called destroy, which performs any required clean-up operations.

fsleyes.gl.resources.exists(key)[source]

Returns True if a resource with the specified key exists, False otherwise.

fsleyes.gl.resources.get(key, createFunc=None, *args, **kwargs)[source]

Return a reference to the resource wiuh the specified key.

If no resource with the given key exists, and createFunc is not None, the resource is created, registered, and returned. If the resource does not exist, and createFunc is None, a KeyError is raised.

Parameters
  • key – Unique resource identifier.

  • createFunc – If the resource does not exist, and this argument is provided, it will be called to create the resource.

All other positional and keyword arguments will be passed through to the createFunc.

fsleyes.gl.resources.set(key, resource, overwrite=False)[source]

Create a new resource, or update an existing one.

Parameters
  • key – Unique resource identifier.

  • resource – The resource itself.

  • overwrite – If False (the default), and a resource with the specified key already exists, a KeyError is raised. Otherwise, it is assumed that a resource with the specified key exists - the existing resource is replaced with the specified resource.

fsleyes.gl.resources.delete(key)[source]

Decrements the reference count of the resource with the specified key. When the resource reference count reaches 0, the destroy method is called on the resource.

Parameters

key – Unique resource identifier.

class fsleyes.gl.resources._Resource(key, resource)[source]

Bases: object

Internal type which is used to encapsulate a resource, and the number of active references to that resources. The following attributes are available on a _Resource:

key

The unique resource key.

resource

The resource itself.

refcount

Number of references to the resource (initialised to 0).

__init__(key, resource)[source]

Create a _Resource.

Parameters
  • key – The unique resource key.

  • resource – The resource itself.

__dict__ = mappingproxy({'__module__': 'fsleyes.gl.resources', '__doc__': 'Internal type which is used to encapsulate a resource, and the\n    number of active references to that resources. The following attributes\n    are available on a ``_Resource``:\n\n    ============ ============================================================\n    ``key``      The unique resource key.\n    ``resource`` The resource itself.\n    ``refcount`` Number of references to the resource (initialised to ``0``).\n    ============ ============================================================\n    ', '__init__': <function _Resource.__init__>, '__dict__': <attribute '__dict__' of '_Resource' objects>, '__weakref__': <attribute '__weakref__' of '_Resource' objects>, '__annotations__': {}})
__module__ = 'fsleyes.gl.resources'
__weakref__

list of weak references to the object (if defined)

fsleyes.gl.resources._resources = {}

A dictionary containing {key : _Resource} mappings for all resources that exist.