Rich Appearance Format (RAF)

Description

RAF (Rich Appearance Format) is a container, used by the animation when PS3 boots (coldboot.raf), and inside dynamic Themes (as the animated scene displayed at the background of the theme)

• RAF related firmware modules in dev_flashvsh/modules/:
  • raf.sprx <--- generic animations

RAF structure

See: CXML Containers page

RAF contents

It must comply with these max restrictions :

-Textures size max: 15 mb ( 15728640 Bytes ) ( on RSX local memory at run time )
-Geometry & script size max: 1 mb ( 1048576 Bytes ) ( on main memory at run time )
-Actor size max: 1.25mb ( 1310720 Bytes ) ( in the intermediate buffer )

-Cameras: 1 (perspective or orthographic)
-Lights: 2 (ambient and/or point)
-Scripts: 1

-Actors: 128
 -Models: 64 per actor ?
  -Animations: 8 per model
 -Materials: 1 per actor ?
  -Textures: 4 per material ?

RAF Scene (.XML)

A RAF animation consists in an "scene" (think in it like a theatre performance), viewed from a "camera" (think in it as the frame of your TV), is visible because there are "lights" (lights are mandatory otherway the scene will be completly in darkness), and is performed using an "script" file (think in it like the theatre director)

The most important element of a scene are the "actors" that are composed by a "model" (for an human the model is his body surface, or parts of his body) and a "material" (for an human the material of his body is flesh, or clothes for some of his body parts)

The "model" is associated with an "animation" (otherway it will not move) and the "material" is associated with a "texture" (for an human the texture is his skin, think in the textures as stickers you place over the model surface)

So an "actor" is composed by one or several "model" (associated with an "animation"), and a "material" (associated with a "texture")

The camera and lights are a bit special, there are different 2 ways to integrate them in the scene because are not visible (is imposible to see the camera because you are looking at the scene from inside of the camera) and lights are just light rays (the emitter is not visible, only the rays)... For this reason camera and lights can be completly defined in the scene.xml (so no need to create 3D object for them)... but they also admits to be defined as 3D objects (for this method is needed to create 3D objects for them, this allows for more complex lights animations or cinematic effects like camera travellings)

<?xml version='1.0' encoding="UTF-8"?>

<raf angle_unit="radian/degree">

	<model id="model" file="model.dae" vertex_color="disable/enable" >
		<animation id="animation" file="animation.dae" start="1" end="100" sampling_rate="1" />
	</model>

	<material id="material" effect="pure_texture/pure_texture_alpha_0_depth_1/pure_texture_alpha_1_depth_0/pure_texture_alpha_0_depth_0/basic_lighting/basic_lighting_alpha_0/basic_lighting_edge_lit/basic_lighting_edge_lit_alpha_0/basic_lighting_alpha_add" >
		<texture file="texture.jpg/texture.dds" type="color_map/normal_map/specular_map/tangent_normal_map" />
	</material>

	<actor id="actor" model="model" material="material" position="x,y,z" rotation="x,y,z" scale="x,y,z" color="r,g,b,a" uv_scale="u,v" uv_offset="u,v" anim_weight="anim0, anim1, anim2, anim3" anim_speed="anim0, anim1, anim2, anim3" anim_time="anim0, anim1, anim2, anim3" />

	<camera id="camera" file="camera.dae" type="perspective/orthographic" yfov="1" ymag="1" znear="1" zfar="1" position="x,y,z" direction="x,y,z" up="x,y,z" />

	<light id="light" file="light.dae" type="ambient/point" color="r,g,b" position="x,y,z" direction="x,y,z" attenuation="1,1,1" />

	<script file="script.js" />

</raf>

• Notes
  • The maximum length of the string that can be specified to the id attribute of an element is 31 characters
  • Time is in seconds
  • A vector (in code) is composed by a group of datas, the number or the type of this datas can be different:
    • For 3D space "x, y, z" are the values of the axis that defines a point, rotation, scale, a direction etc...
    • For colors "r, g, b, a" are red, green, blue channels, and alpha for transparency
    • For textures "u, v" represents displacement in the x and y axis when the texture is applyed over a 2D surface

<raf>

Attribute	Description
angle_unit	Unit of angles in the scene file (radian/degree)

• Angles values conversions notes goes here ???

Model

<model>

Attribute	Description
id	String accessed as the model attribute of the <actor> element
file	Path to the model's .dae file exported by the DCC tool
vertex_color	Usage (or lack) of color regarding each vertex enable/disable

Animation

<animation>

Attribute	Description
id	String accessed by scripts
file	Path to the animation's .dae file exported by the DCC tool
start	Start time
end	End time
sampling_rate	Sampling rate

Material

<material>

Attribute	Description
id	String accessed as the material attribute of the <actor> element
effect	String specifying the effect. Effects are selected from the preset values in the system software. pure_texture : No lighting. Display the texture as is. pure_texture_alpha_0_depth_1 : Remove alpha from pure_texture pure_texture_alpha_1_depth_0 : Remove depth from pure_texture pure_texture_alpha_0_depth_0 : Remove alpha and depth from pure_texture basic_lighting : Basic lighting basic_lighting_alpha_0 : Remove alpha from basic_lighting basic_lighting_edge_lit : Throw light on object's edges in addition to basic_lighting basic_lighting_edge_lit_alpha_0 : Remove alpha from basic_lighting_edge_lit basic_lighting_alpha_add : Derive blending of basic_lighting by addition calculation sce01 : internal/reserved ? (used in coldboot.raf compiled with raf tools v1.00)

Texture

<texture>

Attribute	Description
file	Path to the texture file
type	String specifying the texture map method. This is selected from the preset values in the system software: color_map : Color (RGBA) normal_map : Normal in object space (RGB) specular_map : Specular strength (G) tangent_normal_map : Normal in tangent space, valid only for models with TEXTANGENT (RGB)

Actor

<actor>

Attribute	Description
id	String accessed by scripts
model	String that accesses the id attribute of the <model> element
material	String that accesses the id attribute of the <material> element
position	Vector to the initial position (x, y, z)
rotation	Vector to the initial rotation angle (x, y, z)
scale	Vector to the initial scale (x, y, z)
color	Vector to the initial color (r, g, b, a)
uv_scale	Vector to the texture coordinates' initial scale (u, v)
uv_offset	Vector to the texture coordinates' initial offset (u, v)
anim_weight	Vector to the animation's initial blend weights (anim0, anim1, anim2, anim3)
anim_speed	Vector to the animation's initial speed (anim0, anim1, anim2, anim3)
anim_time	Vector to the animation's initial time (anim0, anim1, anim2, anim3)
zsort	String indicating the z sort type (unspecified/back to front/front to back)

• zsort was not supported in raf tools v1 (the version used to build coldboot.raf), it was implemented in later versions of the raf tools, because this reason the "actors" in coldboot.raf doesnt uses zsort, see Coldboot.raf#Scene

Camera

<camera>

Attribute	Description
id	String accessed by scripts
file	Path to the camera's .dae file exported by the DCC tool (if .dae is used)
type	String indicating the camera type (perspective/orthographic)
yfov	Scalar indicating the field-of-view in the vertical direction (perspective only)
ymag	Scalar indicating the magnification in the vertical direction (orthographic only)
znear	Scalar indicating the near clip plane
zfar	Scalar indicating the far clip plane
position	Vector to the initial position (x, y, z)
direction	Vector to the initial direction (x, y, z)
up	Vector to the initial up direction (x, y, z)

Light

<light>

Attribute	Description
id	String accessed by scripts
file	Path to the light's .dae file exported by the DCC tool (if .dae is used)
type	String indicating the light type (ambient/point)
color	Vector to the initial color (r, g, b)
position	Vector to the initial position (x, y, z)
direction	Vector to the initial direction (x, y, z)
attenuation	Vector to the initial attenuation (zero-order, first-order, second-order)

Script

<script>

Attribute	Description
file	Path to the script file

Lights, Camera, Models, Animations (.DAE)

Dae files are geometric 3D objects, generated by collada plugin from one of the collada supported 3D tools (blender, maya, 3dmax, etc...)

The raf scene.xml takes .dae files as inputs, this files are converted to .edge and .skel (both seems raw geometric vertex info) and .anim (probably containing raw geometric vertex info + time keyframes)

Dae files are xml based, and contains references to the libraries that were used by the 3D tool that build the object, this info is a collada standard and most of it is ignored when converted to .skel and .edge... in other words, most of the .dae info is lost when the .dae file is stored inside the .raf file (though is supposed to have some relationship with the graphic libraries availables in ps3 firmware)

• Typical entries found in models (3d objects)
  • <asset>
  • <library_physics_scenes>
  • <library_images>
  • <library_materials>
  • <library_effects>
  • <library_geometries>
  • <library_visual_scenes>
  • <scene>

• Typical entries found in models (3d lights)
  • <asset>
  • <library_physics_scenes>
  • <library_lights>
  • <library_visual_scenes>
  • <scene>

Textures (.JPG .DDS)

See Multimedia Formats and Tools page

Before compiling, only .DDS and .JPG are supported.

After compiling, .DDS files are converted to .GTF. And .JPG files are stored as .JPG without conversion

GTF (Graphics Texture Format) is a container for storing one or multiple textures, the stored textures uses the same layout than if there was stored in PS3 RAM, this way is posible to make a direct copy of the textures to ram without any conversion to make them available for RSX as soon as possible

Script (.JS)

The raf scene.xml takes as input an script with file extension .js written in PlayStation JavaScript language

This script is converted into an intermediate .jsx file in VSMX format, and then stored inside the .raf file.

• Some examples of PS3 theme using PSJS:
  • http://www.studio-output.com/case_study/the-studio/

RAF tools

Rich Apparence Maker

http://r.a.m.games-hack.fr/index.php

guide http://r.a.m.games-hack.fr/doc/Rich%20Appearance%20Maker%20-%20Quick%20Start%20Guide.pdf

R.A.M on PS3 News: http://www.ps3news.com/ps3-hacks-jailbreak/video-ps3-rich-appearance-maker-r-a-m-beta-is-now-open/

R.A.M on PSX Scene: http://psx-scene.com/forums/content/rich-appearance-maker-r-m-free-beta-now-open-dynamic-theme-maker-2161/

PS3 Color Logo Creator V2.511

PCLC Source: http://tizzyt-archive.blogspot.co.uk/2012/04/playstation-color-logo-creator-v2511.html

PCLC on PS3 News: http://www.ps3news.com/ps3-hacks-jailbreak/ps3-color-logo-creator-v2-50-v2-51-updates-now-available/

PCLC V2.511 Download: http://www.mediafire.com/download/zbb3e07wdx22jub

Links

• RAF pages in other wiki/s
  • https://web.archive.org/web/20141027141848/http://dudu.clx.free.fr/wiki/index.php?title=PS3RAF
  • http://ps3.duduclx.fr/index.php?title=Th%C3%A8mes_dynamiques_PS3
  • https://web.archive.org/web/20141119010210/http://dudu.clx.free.fr/wiki/index.php?title=PS3Them
• Interesting info about Animations/3D support in themes https://web.archive.org/web/20141119010206/http://www.ps3hax.net/showthread.php?t=28426
• See also: Qt Resource Container (QRC)