Skip to content

Commit

Permalink
Textures: Cleanup
Browse files Browse the repository at this point in the history
  • Loading branch information
@danij-deng
danij-deng committed Aug 3, 2012
1 parent dde4234 commit 6151c51
Show file tree
Hide file tree
Showing 2 changed files with 185 additions and 194 deletions.
133 changes: 61 additions & 72 deletions doomsday/engine/portable/include/textures.h
View file
@@ -1,43 +1,35 @@
/**\file textures.h
*\section License
* License: GPL
* Online License Link: http://www.gnu.org/licenses/gpl.html
*
*\author Copyright © 2010-2012 Daniel Swanson <danij@dengine.net>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor,
* Boston, MA 02110-1301 USA
*/

/**
* Textures Collection.
* @ingroup refresh
* @file textures.h
* Textures collection. @ingroup refresh
*
* 'Clear'ing a Texture is to "undefine" it - any names bound to it are
* deleted, any GL textures acquired for it are 'released'. The Texture
* instance record used to represent it is also deleted.
* "Clear"ing a Texture is to 'undefine' it - any names bound to it are deleted,
* any GL textures acquired for it are 'released'. The Texture instance record
* used to represent it is also deleted.
*
* 'Release'ing a Texture will leave it defined (any names bound to it
* will persist) and any GL textures acquired for it are so too released.
* Note that the Texture instance record used to represent it will NOT
* be deleted.
* "Release"ing a Texture will leave it defined (any names bound to it will
* persist) and any GL textures acquired for it are so too released. Note that
* the Texture instance record used to represent it will NOT be deleted.
*
* Thus there are two general states for textures in the collection:
*
* 1) Declared but not defined.
* 2) Declared and defined.
*
* @authors Copyright &copy; 2010-2012 Daniel Swanson <danij@dengine.net>
*
* @par License
* GPL: http://www.gnu.org/licenses/gpl.html
*
* <small>This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by the
* Free Software Foundation; either version 2 of the License, or (at your
* option) any later version. This program is distributed in the hope that it
* will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
* Public License for more details. You should have received a copy of the GNU
* General Public License along with this program; if not, write to the Free
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA</small>
*/

#ifndef LIBDENG_REFRESH_TEXTURES_H
Expand Down Expand Up @@ -72,16 +64,15 @@ void Textures_Init(void);
void Textures_Shutdown(void);

/**
* Try to interpret a texture namespace identifier from @a str.
* If found to match a known namespace name, return the associated identifier.
* If the reference @a str is not valid (i.e., NULL or a zero-length string)
* then the special identifier @c TN_ANY is returned.
* Try to interpret a texture namespace identifier from @a str. If found to match a known
* namespace name, return the associated identifier. If the reference @a str is not valid
* (i.e., NULL or a zero-length string) then the special identifier @c TN_ANY is returned.
* Otherwise @c TN_INVALID.
*/
texturenamespaceid_t Textures_ParseNamespace(const char* str);

/// @return Name associated with the identified @a namespaceId else a zero-length string.
const ddstring_t* Textures_NamespaceName(texturenamespaceid_t namespaceId);
const Str* Textures_NamespaceName(texturenamespaceid_t namespaceId);

/// @return Total number of unique Textures in the collection.
uint Textures_Size(void);
Expand All @@ -101,8 +92,8 @@ void Textures_ClearSystem(void);
/**
* Clear all textures in the identified namespace(s) (and release any acquired GL-textures).
*
* @param namespaceId Unique identifier of the namespace to process
* or @c TN_ANY to clear all textures in any namespace.
* @param namespaceId Unique identifier of the namespace to process or
* @c TN_ANY to clear all textures in any namespace.
*/
void Textures_ClearNamespace(texturenamespaceid_t namespaceId);

Expand All @@ -127,7 +118,7 @@ texturenamespaceid_t Textures_Namespace(textureid_t textureId);

/// @return Symbolic, percent-encoded name/path-to this texture as a string.
/// Must be destroyed with Str_Delete().
ddstring_t* Textures_ComposePath(textureid_t textureId);
Str* Textures_ComposePath(textureid_t textureId);

/// @return URI to this texture, percent-encoded. Must be destroyed with Uri_Delete().
Uri* Textures_ComposeUri(textureid_t textureId);
Expand All @@ -149,61 +140,59 @@ textureid_t Textures_ResolveUriCString2(const char* uri, boolean quiet);
textureid_t Textures_ResolveUriCString(const char* uri); /*quiet=!(verbose >= 1)*/

/**
* Declare a texture in the collection. If a texture with the specified
* @a uri already exists, its unique identifier is returned. If the given
* @a resourcePath differs from that already defined for the pre-existing
* texture, any associated Texture instance is released (and any GL-textures
* acquired for it).
*
* @param uri Uri representing a path to the texture in the virtual hierarchy.
* @param uniqueId Namespace-unique identifier to associate with the texture.
* Declare a texture in the collection. If a texture with the specified @a uri already
* exists, its unique identifier is returned. If the given @a resourcePath differs from
* that already defined for the pre-existing texture, any associated Texture instance
* is released (and any GL-textures acquired for it).
*
* @param uri Uri representing a path to the texture in the virtual hierarchy.
* @param uniqueId Namespace-unique identifier to associate with the texture.
* @param resourcepath The path to the underlying data resource.
* @return Unique identifier for this texture unless @a uri is invalid,
* in which case @c NOTEXTUREID is returned.
*
* @return Unique identifier for this texture unless @a uri is invalid, in which case
* @c NOTEXTUREID is returned.
*/
textureid_t Textures_Declare(const Uri* uri, int uniqueId, const Uri* resourcePath);

/**
* Create/update a Texture instance in the collection.
*
* @param id Unique identifier of the previously declared Texture.
* @param flags @see textureFlags
* @param size Logical size. Components can be @c 0 in which case their value
* will be inherited from the actual pixel size of the texture at load time.
* @param id Unique identifier of the previously declared Texture.
* @param flags @ref textureFlags
* @param size Logical size. Components can be @c 0 in which case their value will
* be inherited from the actual pixel size of the texture at load time.
* @param userData User data to associate with the resultant texture.
*/
struct texture_s* Textures_CreateWithSize(textureid_t id, int flags, const Size2Raw* size, void* userData);
struct texture_s* Textures_Create(textureid_t id, int flags, void* userData); /* width=0, height=0*/

/**
* Iterate over defined Textures in the collection making a callback for
* each visited. Iteration ends when all textures have been visited or a
* callback returns non-zero.
* Iterate over defined Textures in the collection making a callback for each visited.
* Iteration ends when all textures have been visited or a callback returns non-zero.
*
* @param namespaceId If a valid namespace identifier, only consider
* textures in this namespace, otherwise visit all textures.
* @param callback Callback function ptr.
* @param paramaters Passed to the callback.
* @param namespaceId If a valid namespace identifier, only consider textures in this
* namespace, otherwise visit all textures.
* @param callback Callback function ptr.
* @param parameters Passed to the callback.
*
* @return @c 0 iff iteration completed wholly.
*/
int Textures_Iterate2(texturenamespaceid_t namespaceId, int (*callback)(struct texture_s* texture, void* paramaters), void* paramaters);
int Textures_Iterate(texturenamespaceid_t namespaceId, int (*callback)(struct texture_s* texture, void* paramaters)); /*paramaters=NULL*/
int Textures_Iterate2(texturenamespaceid_t namespaceId, int (*callback)(struct texture_s* texture, void* parameters), void* parameters);
int Textures_Iterate(texturenamespaceid_t namespaceId, int (*callback)(struct texture_s* texture, void* parameters)); /*parameters=NULL*/

/**
* Iterate over declared textures in the collection making a callback for
* each visited. Iteration ends when all textures have been visited or a
* callback returns non-zero.
* Iterate over declared textures in the collection making a callback for each visited.
* Iteration ends when all textures have been visited or a callback returns non-zero.
*
* @param namespaceId If a valid namespace identifier, only consider
* textures in this namespace, otherwise visit all textures.
* @param callback Callback function ptr.
* @param paramaters Passed to the callback.
* @param namespaceId If a valid namespace identifier, only consider textures in this
* namespace, otherwise visit all textures.
* @param callback Callback function ptr.
* @param parameters Passed to the callback.
*
* @return @c 0 iff iteration completed wholly.
*/
int Textures_IterateDeclared2(texturenamespaceid_t namespaceId, int (*callback)(textureid_t textureId, void* paramaters), void* paramaters);
int Textures_IterateDeclared(texturenamespaceid_t namespaceId, int (*callback)(textureid_t textureId, void* paramaters)); /*paramaters=NULL*/
int Textures_IterateDeclared2(texturenamespaceid_t namespaceId, int (*callback)(textureid_t textureId, void* parameters), void* parameters);
int Textures_IterateDeclared(texturenamespaceid_t namespaceId, int (*callback)(textureid_t textureId, void* parameters)); /*parameters=NULL*/

#ifdef __cplusplus
} //extern "C"
Expand Down

0 comments on commit 6151c51

Please sign in to comment.