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)¶ Returns
True
if a resource with the specified key exists,False
otherwise.
-
fsleyes.gl.resources.
get
(key, createFunc=None, *args, **kwargs)¶ Return a reference to the resource wiuh the specified key.
If no resource with the given key exists, and
createFunc
is notNone
, the resource is created, registered, and returned. If the resource does not exist, andcreateFunc
isNone
, aKeyError
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)¶ 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 specifiedkey
already exists, aKeyError
is raised. Otherwise, it is assumed that a resource with the specifiedkey
exists - the existing resource is replaced with the specifiedresource
.
-
fsleyes.gl.resources.
delete
(key)¶ Decrements the reference count of the resource with the specified key. When the resource reference count reaches
0
, thedestroy
method is called on the resource.Parameters: key – Unique resource identifier.
-
class
fsleyes.gl.resources.
_Resource
(key, resource)¶ 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)¶ 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>})¶
-
__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.