PS2Icon Class Reference

A loader for PS2 icon files. More...

#include <ps2_ps2icon.hpp>

List of all members.

Public Types

typedef struct
PS2Icon::Icon_Header_t 
Icon_Header
typedef struct
PS2Icon::Vertex_Coord_t 
Vertex_Coord
typedef struct
PS2Icon::Texture_Data_t 
Texture_Data
typedef struct
PS2Icon::Animation_Header_t 
Animation_Header
typedef struct
PS2Icon::Frame_Data_t 
Frame_Data
typedef struct PS2Icon::Frame_Key_t Frame_Key

Public Member Functions

 PS2Icon ()
 Constructor.
 PS2Icon (char const *fname)
 Constructor.
 ~PS2Icon ()
 Destructor.
int GetNVertices () const
 Get the number of vertices of the icon.
int GetNShapes () const
 Get the number of shapes per vertex.
int GetNFrames () const
 Get the number of frames in the animation.
int GetFrameShape (int frame) const
 Get the number of the shape used in a specific frame.
int GetNFrameKeys (int frame) const
 Get the number of keys used in a specific frame.
float GetFrameKeyTime (int frame, int key) const
 Get the time key for a specific frame and key.
float GetFrameKeyValue (int frame, int key) const
 Get the value key for a specific frame and key.
int GetTextureType () const
 Get the texture type.
void GetVertexData (float *data, int shape) const
 Get the vertex data used in a specific shape.
void GetVertexColorData (unsigned int *data) const
 Get the per-vertex color data.
void GetNormalData (float *data) const
 Get the per-vertex normal data.
void GetVertexTextureData (float *data) const
 Get the per-vertex texture coordinates.
void GetTextureData (unsigned int *data) const
 Get the complete texture data block.
void GetTextureData (unsigned int *data, int pitch) const
 Copy the complete texture block to a pitched field.
unsigned int GetTextureData (int x, int y) const
 Get the color value of a specific pixel in the texture.
void WriteFile (char const *fname) const
 Save the current data to a new icon file.
void SetGeometry (OBJ_Mesh const &mesh)
 Set the geometry data of the icon.
void SetGeometry (OBJ_Mesh const &mesh, float scale_factor)
 Set the geometry data of the icon.
void SetGeometry (float const *pverts, float const *pnormals, float const *ptexture, int n_vertices)
 Set the geometry data of the icon.
void SetTextureData (unsigned int const *data)
 Set the texture data of the icon.
void BuildMesh (OBJ_Mesh *mesh)
 Build a mesh from current data.

Classes

struct  Animation_Header_t
 Animation header. More...
struct  Frame_Data_t
 Per-frame animation data. More...
struct  Frame_Key_t
 Per-key animation data. More...
struct  Icon_Header_t
 File header. More...
struct  Texture_Data_t
 Set of texture coordinates. More...
struct  Vertex_Coord_t
 Set of vertex coordinates. More...


Detailed Description

A loader for PS2 icon files.

This class can be used to read and write icon files.

Note:
Currently all structs defined in this class are assumed to be unpadded! This doesn't prove to be a problem yet, but keep it in mind anyhow!

This class keeps two representations of most of its data. Aside from the representation also used in the file, there is also a representation that fits the standards of modern graphic APIs for visualization.

Todo:
SetAnimation

The file format

The file is made up of the following segments:

The file header

The file header is defined by the Icon_Header_t struct and is pretty straightforward. It stores the number of vertices present as well as the number of animation shapes which are both required to calculate the offset to the animation header segment. The file header is always 20 bytes in size.

The vertex data segment

PS2 Icons store all vertex data linearly and unindexed. The vertex segment consists of (n_vertices) different entries of the following structure:

The animation header

The animation header is defined by Animation_Header_t. Little is known about those values, except that there is one entry specifying the number of frames present in the animation.
Note:
Notice that the number of frames is not the same as the number of shapes! A shape can be used in several frames in order to to compose complex animation with little memory overhead.

The animation data segment

The animation data segment holds n_frames entries, each consisting of:

The texture data segment

Each icon has a 128*128 pixel texture attached, with 16 bits reserved for each pixel. The color format is presumably ABBBBBGGGGGRRRRR where the exact purpose of the alpha bit is yet to be discovered. If the texture_type value in the header has a value of 0x07 or higher the texture data is encoded with a simple RLE algorithm, which was documented in detail by Martin Akesson.

Remarks:
Currently the framework assumes that none of the 32 bit unsigned integer values present in a file exceeds INT_MAX. If at some point a value is encountered, that is greater than INT_MAX and can thus not be safely cast to an int, an exception will be thrown. However, this should never occur in a real world example.

Constructor & Destructor Documentation

PS2Icon::PS2Icon (  ) 

Constructor.

Note:
This just fills the fields with default values. To obtain a valid file you must at least call SetGeometry() before writing.

PS2Icon::PS2Icon ( char const *  fname  ) 

Constructor.

Parameters:
[in] fname Complete path to a valid icon file
Exceptions:
Ghulbus::gbException GB_FAILED indicates a file access error;
std::bad_alloc 


Member Function Documentation

int PS2Icon::GetNVertices (  )  const

Get the number of vertices of the icon.

Returns:
The number of vertices of the icon
Exceptions:
Ghulbus::gbException GB_FAILED uint overflow;

int PS2Icon::GetNShapes (  )  const

Get the number of shapes per vertex.

Returns:
The number of shapes of the icon
Exceptions:
Ghulbus::gbException GB_FAILED uint overflow;

int PS2Icon::GetNFrames (  )  const

Get the number of frames in the animation.

Returns:
The number of frames of the icon
Exceptions:
Ghulbus::gbException GB_FAILED uint overflow;

int PS2Icon::GetFrameShape ( int  frame  )  const

Get the number of the shape used in a specific frame.

Parameters:
[in] frame Number of the frame [0..(n_frames-1)]
Returns:
The number of the shape used in frame [0..(animation_shapes-1)]
Exceptions:
Ghulbus::gbException GB_FAILED uint overflow; GB_ILLEGALPARAMETER;

int PS2Icon::GetNFrameKeys ( int  frame  )  const

Get the number of keys used in a specific frame.

Parameters:
[in] frame Number of the frame [0..(n_frames-1)]
Returns:
Number of keys used in frame
Exceptions:
Ghulbus::gbException GB_FAILED uint overflow; GB_ILLEGALPARAMETER;

float PS2Icon::GetFrameKeyTime ( int  frame,
int  key 
) const

Get the time key for a specific frame and key.

Parameters:
[in] frame Number of the frame [0..(n_frames-1)]
[in] key Number of the key [0..(animation[frame].n_keys-1)]
Returns:
The time key used in frame, key
Exceptions:
Ghulbus::gbException GB_ILLEGALPARAMETER;

float PS2Icon::GetFrameKeyValue ( int  frame,
int  key 
) const

Get the value key for a specific frame and key.

Parameters:
[in] frame Number of the frame [0..(n_frames-1)]
[in] key Number of the key [0..(animation[frame].n_keys-1)]
Returns:
The value key used in frame, key
Exceptions:
Ghulbus::gbException GB_ILLEGALPARAMETER;

int PS2Icon::GetTextureType (  )  const

Get the texture type.

Returns:
The texture type id (>=0x07: uncompressed; <=0x07: rle encoded)
Exceptions:
Ghulbus::gbException GB_FAILED uint overflow;

void PS2Icon::GetVertexData ( float *  data,
int  shape 
) const

Get the vertex data used in a specific shape.

Parameters:
[out] data A field of at least size (n_vertices * 3), resp. (n_vertices * n_shapes * 3)
[in] shape A positive integer specifies the shape; A negative integer causes all shapes to be copied to data sequentially
Exceptions:
Ghulbus::gbException GB_ILLEGALPARAMETER;

void PS2Icon::GetVertexColorData ( unsigned int *  data  )  const

Get the per-vertex color data.

Parameters:
[out] data A field of at least size (n_vertices)

void PS2Icon::GetNormalData ( float *  data  )  const

Get the per-vertex normal data.

Parameters:
[out] data A field of at least size (n_vertices * 3)

void PS2Icon::GetVertexTextureData ( float *  data  )  const

Get the per-vertex texture coordinates.

Parameters:
[out] data A field of at least size (n_vertices * 2)

void PS2Icon::GetTextureData ( unsigned int *  data  )  const

Get the complete texture data block.

Parameters:
[out] data A field of at least size 16384

void PS2Icon::GetTextureData ( unsigned int *  data,
int  pitch 
) const

Copy the complete texture block to a pitched field.

Parameters:
[out] data A field of at least size (16384 * sizeof(unsigned int))
[in] pitch The size of each row in data in bytes
Exceptions:
Ghulbus::gbException GB_ILLEGALPARAMETER;

unsigned int PS2Icon::GetTextureData ( int  x,
int  y 
) const

Get the color value of a specific pixel in the texture.

Parameters:
[in] x X-coordinate [0..127]
[in] y Y-coordinate [0..127]
Returns:
The texel value (D3DCOLOR format)
Exceptions:
Ghulbus::gbException GB_ILLEGALPARAMETER;

void PS2Icon::WriteFile ( char const *  fname  )  const

Save the current data to a new icon file.

Parameters:
[in] fname The full path of the destination file
Exceptions:
Ghulbus::gbException GB_FAILED file access error;

void PS2Icon::SetGeometry ( OBJ_Mesh const &  mesh  ) 

Set the geometry data of the icon.

Parameters:
[in] mesh A valid OBJ_Mesh object holding new geometry data
Exceptions:
std::bad_alloc 

void PS2Icon::SetGeometry ( OBJ_Mesh const &  mesh,
float  scale_factor 
)

Set the geometry data of the icon.

Parameters:
[in] mesh A valid OBJ_Mesh object holding new geometry data
[in] scale_factor A factor that is multiplied onto each vertex for scaling
Exceptions:
std::bad_alloc 

void PS2Icon::SetGeometry ( float const *  pverts,
float const *  pnormals,
float const *  ptexture,
int  n_vertices 
)

Set the geometry data of the icon.

Parameters:
[in] pverts A field of at least size n_vertices*3 holding vertex data
[in] pnormals A field of at least size n_vertices*3 holding normal data
[in] ptexture A field of at least size n_vertices*2 holding 2D texture coordinate data
[in] n_vertices Number of vertices

void PS2Icon::SetTextureData ( unsigned int const *  data  ) 

Set the texture data of the icon.

Parameters:
[in] data A field of at least size 16384 containing 32 bit image data

void PS2Icon::BuildMesh ( OBJ_Mesh mesh  ) 

Build a mesh from current data.

Parameters:
[in,out] mesh A mesh object that will be filled with the icon geometry

Todo:
: vertex recycling?


The documentation for this class was generated from the following files:
Generated on Sat Jan 19 18:58:22 2008 for PS2 IconSys Library by  doxygen 1.5.4