Index

Package: Resources

Description

package Resources is

Classes

Resource_File

type Resource_File is tagged limited private;
A Resource_File represents a resource file loaded in memory. The contents of the file can be accessed via various methods. Once a Resource_File is closed, its backing data should no longer be relied upon. If the file data is required after the Resource_File must be closed, a copy of the contents should be made. Resource files are cached to avoid the cost of searching and reading from disk each time file is needed but the details of the cache and how/when it is purged are private.

Tasks & Protected

Async_Operation (protected type)

A protected state object useful for asynchronously loading resources

Types

A_Async_Operation

type A_Async_Operation is access all Async_Operation;

A_Resource_File

type A_Resource_File is access all Resource_File'Class;

Constants & Global variables

RESOURCE_ERROR

RESOURCE_ERROR,
    RESOURCE_FORMAT_ERROR : exception;

RESOURCE_FORMAT_ERROR

RESOURCE_FORMAT_ERROR : exception;

Subprograms & Entries

Async_Operation. Complete

procedure Complete;
Notifies the object that the operation is complete. This will unblock all threads blocked on the Wait entry.

Async_Operation. Is_Complete

function Is_Complete return Boolean;
Checks the state of the operation without waiting for completion.

Async_Operation. Wait (abstract)

entry Wait;
Blocks the caller until the operation is complete.

Delete

procedure Delete
( op: in out A_Async_Operation );
Deletes the Async_Operation.

Loading_Begins

procedure Loading_Begins;
Notifies the application that resource loading is beginning. If loading was not in progress then a Loading_Event(loading => True) will be queued.

Loading_Ends

procedure Loading_Ends;
Notifies the application that resource loading has ended. If loading was was in progress then a Loading_Event(loading => False) will be queued.

Get_Address

function Get_Address
( this: not null access Resource_File'Class ) return Address;
Returns the address of the resource file's data. The length of the data can be determined by calling Size.

Get_Filename

function Get_Filename
( this: not null access Resource_File'Class ) return String;
Returns the filename of the resource.

Get_Id

function Get_Id
( this: not null access Resource_File'Class ) return String;
Returns an identifying string comprised of the original filepath and group name used to find the resource.

Get_Packfile

function Get_Packfile
( this: not null access Resource_File'Class ) return A_Packfile;
Returns a packfile reference to the resource. Be sure to close the packfile before unloading the resource.

Get_Stream

procedure Get_Stream
( this: not null access Resource_File'Class;
strm: out A_Buffer_Stream );
Returns a new read-only stream backed by the resource contents. Be sure to close the stream before unloading the resource.

Size

function Size
(this: not null access Resource_File'Class ) return Unsigned_32;
Returns the size of the file in bytes;

Load_Resource

function Load_Resource
( filepath: String;
group: String;
cache: Boolean ) return A_Resource_File;
Searches for and loads a resource file, returning a reference to it. The search order for resources files is as follows: 1. filepath (If filepath is an absolute file path) 2. working_dir/filename 3. working_dir/group.zip/filename 4. media_dir/filename 5. media_dir/group.zip/filename (Where 'filename' is the filename taken from 'filepath'.) NULL will be returned if the file is not found or can't otherwise be accessed. Resource files are reference counted, so you must call Unload_Resource when finished with the Resource_File. If 'cache' is True, the resource will be kept in memory even after no references remain. This is useful for keeping a resource cached in memory for the life of the application.

Preload_Resource

procedure Preload_Resource
( filepath: String;
group: String );
Loads a resource into memory in the same way as Load_Resource except the reference will not be returned and the internal reference count will begin at zero. Use this to prefetch resources from disk. No load errors are reported by this procedure.

Unload_Resource

procedure Unload_Resource
( resource: in out A_Resource_File );
Unloads a resource file. Resource files are reference counted so be sure to call this when finished with a Resource_File.

Write_Path

function Write_Path
( filepath: String;
group: String ) return String;
Returns the location where a file can be written to overwrite an existing resource if possible or override an existing resource that is in an archive. The specified file will searched for with the same algorithm as Load_Resource. If the resource file is found and it's not in an archive, its absolute path will be returned. If the file was found in an archive or couldn't be found at all, then the returned path will point to a file of the same name in the executable directory.