NAME

OpenGL::Sandbox::ResMan - Resource manager for OpenGL prototyping

VERSION

version 0.041

SYNOPSIS

  my $r= OpenGL::Sandbox::ResMan->default_instance;
  my $tex= $r->tex('foo');
  my $font= $r->font('default');

DESCRIPTION

This object caches references to various OpenGL resources like textures and fonts. It is usually instantiated as a singleton from "default_instance" or from importing the $res variable from OpenGL::Sandbox. It pulls resources from a directory of your choice. Where possible, files get memory-mapped directly into the library that uses them, which should keep the overhead of this library as low as possible.

Note that you need to install OpenGL::Sandbox::V1::FTGLFont in order to get font support, currently. Other font providers might be added later.

ATTRIBUTES

resource_root_dir

The path where resources are located, adhering to the basic layout of:

  ./tex/          # textures
  ./tex/default   # file or symlink for default texture.  Required.
  ./font/         # fonts compatible with libfreetype
  ./font/default  # file or symlink for default font.  Required.

font_config

A hashref of font names which holds default OpenGL::Sandbox::Font constructor options. The hash key of '*' can be used to apply default values to every font. The font named 'default' can be configured here instead of needing a file of that name in the font/ directory.

Example font_config:

  {
    '*'     => { face_size => 48 }, # default settings get applied to all configs
    3d      => { face_size => 64, type => 'FTExtrudeFont' },
    default => { face_size => 32, filename => 'myfont1' }, # font named 'default'
    myfont2 => 'myfont1',  # alias
  }

tex_config

A hashref of texture names which holds default OpenGL::Sandbox::Texture constructor options. The hash key of '*' can be used to apply default values to every texture. The texture named 'default' can be configured here instead of needing a file of that name in the tex/ directory.

Example tex_config:

  {
    '*'     => { wrap_s => GL_CLAMP,  wrap_t => GL_CLAMP  },
    default => { filename => 'foo.png' }, # texture named "default"
    tile1   => { wrap_s => GL_REPEAT, wrap_t => GL_REPEAT },
    blocky  => { mag_filter => GL_NEAREST },
    alias1  => 'tile1',
  }

METHODS

new

Standard Moo constructor. Also validates the resource directory by loading "font/default", which must exist (either a file or symlink)

default_instance

Return a default instance which uses the current directory as "resource_root_dir".

release_gl

Free all OpenGL resources currently referenced by the texture and image cache.

font

  $font= $res->font( $name );

Retrieve a named font, loading it if needed. See "load_font".

If the font cannot be loaded, this logs a warning and returns the 'default' font rather than throwing an exception or returning undef.

load_font

  $font= $res->load_font( $name, %config );

Load a font by name. By default, a font file of the same name is loaded as a TextureFont and rendered at 24px. If multiple named fonts reference the same file (including hardlink checks), it will only be mapped into memory once.

Any configuration options specified here are combined with any defaults specified in "font_config".

If the font can't be loaded, this throws an exception. If the named font has already been loaded, this will return the existing font, even if the options have changed.

load_fontdata

  $mmap= $res->load_fontdata( $name );

Memory-map the given font file. Dies if the font doesn't exist. A memory-mapped font file can be shared between all the renderings at different resolutions.

tex

  my $tex= $res->tex( $name );

Load a texture by name, or return the 'default' texture if it doesn't exist.

load_texture

  my $tex= $res->load_texture( $name )

Load a texture by name. It first checks for a file of no extension, which may be an image file, cached texture file, or symlink/hardlink to another file. Failing that, it checks for a file of that name with any file extension, and attempts to load them in whatever order they were returned.

Dies if no matching file can be found, or if it wasn't able to process any match.

clear_cache

Call this method to remove all current references to any resource. If this was the last reference to those resources, it will also garbage collect any OpenGL resources that had been allocated. The next access to any font or texture will re-load the resource from disk.

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019 by Michael Conrad.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm OpenGL::Sandbox

perl -MCPAN -e shell
install OpenGL::Sandbox