Star Star Star Star Star Star Star Star Star Star Star Star

Changes between Version 3 and Version 4 of documentation/C++Manual/Interfaces

Show
Ignore:
Author:
peterc (IP: 203.96.63.172)
Timestamp:
04/08/08 13:20:15 (9 years ago)
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • documentation/C++Manual/Interfaces

    v3 v4  
    9191{{{ 
    9292// Called by Rocket when it wants to render geometry that the application does not wish to optimise. 
    93 virtual void RenderGeometry(Rocket::Core::Vertex* vertices, int num_vertices, int* indices, int num_indices, const Rocket::Core::Texture* texture, const EMP::Core::Vector2f& translation) = 0; 
     93virtual void RenderGeometry(Rocket::Core::Vertex* vertices, int num_vertices, int* indices, int num_indices, Rocket::Core::TextureHandle texture, const EMP::Core::Vector2f& translation) = 0; 
    9494}}} 
    9595 
    96 All geometry from Rocket is given in this format of indexed triangles. ''vertices'' is an array of vertices making up the geometry. Each vertex is a ''Rocket::Core::Vertex'' type, defined in <Rocket/Core/Vertex.h>. ''num_vertices'' is number of vertices in the array; no index will be equal to or higher than this number. ''indices'' is an array of integer indices, each indexing a single vertex from the vertex array. ''num_indices'' is the total number of indices in the array; as all geometry is given in triangles, this will always be a multiple of three. ''texture'' is a pointer to the texture to be applied to the geometry; this will be NULL for untextured geometry. Lastly, ''translation'' is the 2D translation to be applied to the geometry. 
     96All geometry from Rocket is given in this format of indexed triangles. ''vertices'' is an array of vertices making up the geometry. Each vertex is a ''Rocket::Core::Vertex'' type, defined in <Rocket/Core/Vertex.h>. ''num_vertices'' is number of vertices in the array; no index will be equal to or higher than this number. ''indices'' is an array of integer indices, each indexing a single vertex from the vertex array. ''num_indices'' is the total number of indices in the array; as all geometry is given in triangles, this will always be a multiple of three. ''texture'' is the application-defined handle to the texture to be applied to the geometry; this will be NULL for untextured geometry. Lastly, ''translation'' is the 2D translation to be applied to the geometry. 
    9797 
    9898All physical coordinates (the vertex positions and the geometry translation) are given in pixel offsets from the top-left of the current context being rendered. 
    106106{{{ 
    107107// Called by Rocket when it wants to compile geometry it believes will be static for the forseeable future. 
    108 virtual Rocket::Core::CompiledGeometryHandle CompileGeometry(Rocket::Core::Vertex* vertices, int num_vertices, int* indices, int num_indices, const Rocket::Core::Texture* texture); 
     108virtual Rocket::Core::CompiledGeometryHandle CompileGeometry(Rocket::Core::Vertex* vertices, int num_vertices, int* indices, int num_indices, Rocket::Core::TextureHandle texture); 
    109109 
    110110// Called by Rocket when it wants to render application-compiled geometry. 
    147147{{{ 
    148148// Called by Rocket when a texture is required by the library. 
    149 virtual bool LoadTexture(Rocket::Core::Texture* texture, const EMP::Core::String& source, const EMP::Core::String& source_path) = 0; 
     149virtual bool LoadTexture(Rocket::Core::TextureHandle& texture_handle, 
     150                         EMP::Core::Vector2i& texture_dimensions, 
     151                         const EMP::Core::String& source, 
     152                         const EMP::Core::String& source_path) = 0; 
    150153 
    151154// Called by Rocket when a texture is required to be built from an internally-generated sequence of pixels. 
    152 virtual bool GenerateTexture(Rocket::Core::Texture* texture, const EMP::Core::byte* source) = 0; 
     155virtual bool GenerateTexture(Rocket::Core::TextureHandle& texture_handle, 
     156                             const EMP::Core::byte* source, 
     157                             const EMP::Core::Vector2i& source_dimensions) = 0; 
    153158 
    154159// Called by Rocket when a loaded texture is no longer required. 
    155 virtual void ReleaseTexture(Rocket::Core::Texture* texture) = 0; 
     160virtual void ReleaseTexture(Rocket::Core::TextureHandle texture_handle) = 0; 
    156161}}} 
    157162 
    158 LoadTexture() is called when Rocket wants to load a texture from an external source (usually a file, but this is up to the application). ''source'' is the source name specified in the RML (for an image tag) or RCSS (for a decorator image reference). ''source_path'' is the path of the referencing document. The ''texture'' parameter is a pointer to a ''Rocket::Core::Texture'' structure to be filled if the texture load succeeded. The ''Rocket::Core::Texture'' structure is defined in <Rocket/Core/Texture.h>, and given below: 
    159  
    160 {{{ 
    161 struct Rocket::Core::Texture 
    162 { 
    163         EMP::Core::Vector2i dimensions; 
    164         Rocket::Core::TextureHandle handle; 
    165 }; 
    166 }}} 
    167  
    168 ''dimensions'' should be set to the x- and y-dimensions of the loaded texture, and ''handle'' to a non-NULL unique handle the application can use to identify the texture. Like the other handles, it is a void pointer, and NULL is reserved for invalid handles. 
     163LoadTexture() is called when Rocket wants to load a texture from an external source (usually a file, but this is up to the application). ''source'' is the source name specified in the RML (for an image tag) or RCSS (for a decorator image reference). ''source_path'' is the path of the referencing document. The ''texture_handle'' parameter is a reference to a ''Rocket::Core::TextureHandle'' type. This is a void*, and can be set to whatever you need to uniquely identify the loaded texture (except 0, which is reserved for an invalid texture). ''texture_dimensions'' should be set to the x- and y-dimensions of the loaded texture. 
    169164 
    170165If the LoadTexture() function succeeds in loading the texture, it should return true. Otherwise it should return false. 
    171166 
    172 GenerateTexture() is used by the font system to convert raw pixel data to a texture. The ''texture'' parameter is a pointer to a ''Rocket::Core::Texture'' object, as in LoadTexture(), but the ''dimensions'' variable has been populated with the dimensions of the raw texture data. ''handle'' still needs to be set to the application-specific texture handle. The raw pixel data is given in ''source''; this is an array of unsigned, 8-bit values in RGBA order. It is laid out in tightly-packed rows, so is exactly (dimensions.x * dimensions.y * 4) bytes in size. 
     167GenerateTexture() is used by the font system to convert raw pixel data to a texture. The ''texture_handle'' parameter is a reference to a ''Rocket::Core::TextureHandle'' type to be set, as in LoadTexture(). The raw pixel data is given in ''source''; this is an array of unsigned, 8-bit values in RGBA order. It is laid out in tightly-packed rows, so is exactly (source_dimensions.x * source_dimensions.y * 4) bytes in size. The ''source_dimensions'' variable is set to the dimensions of the raw texture data. 
    173168 
    174169ReleaseTexture() is called with a texture handle once it is no longer required by Rocket.