- Main Page
- Namespaces
- Classes
- Files
- Related Pages

- Class List
- Class Hierarchy
- Class Members

# 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:

- A file header
- A vertex data segment
- An animation header
- An animation data segment
- A texture data segment

### 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:

- First, (animation_shapes) entries of type Vertex_Coord_t specifying the vertex's position in space
- Followed by one entry of type Vertex_Coord_t specifying the normal for that vertex
- Followed by one entry of type Texture_Data_t specifying texture coordinates and color for that vertex Notice that, while a single vertex usually has a different position in each shape, it always has the same normal and texture data!

### 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:

- First, a Frame_Data_t struct, specifying the used shape and the number of keys that follow.
- Then (n_keys) numbers of Frame_Key_t specifying additional information about the frame; The exact semantics of the key are unknown.
  Note:
    The documentation by Martin Akesson claims that the Frame_Data_t is actually 16 bytes large, which is probably a typo.

### 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:

- include/ps2_ps2icon.hpp
- src/ps2_ps2icon.cpp