Yinsh   Rez Advance   Oil Painter

XML Scene File Specifications
The program uses XML scene files as configuration. Unless specified, elements can appear in any order, the only exception is that frames and particles must appear in order of ascending time values. XML files are assumed to be in proper syntax, and all required elements are included to properly generate a scene. Specification:

<painter>…</painter>
Contained-in: Root
Contains: resolution, btex, bgcolor, bmp, demo, output
Comments: The painter element is the only required element in the scene file. It is used as the principle initialization information for the program.

<resolution>w,h</resolution>
Contained-in: painter
Contents: w: Screen Width, h: Screen height
Comments: Specifies the screen resolution/window size for the animation mode.

<btex>filename.bmp</btex>
Contained-in: painter
Contents: filename: an 8-bit greyscale .bmp file with dimensions in powers of 2
Comments: This texture is used as the alpha map for brush strokes

<bgcolor>r,g,b</bgcolor>
Contained-in: painter
Contents: r,g,b: red, green and blue colour parameters over the range [0..255]
Comments: Specifies the background and canvas colour

<bmp>filename.bmp</bmp>
Contained-in: painter
Contents: filename: a 24-bit RGB .bmp file with dimensions divisible by 8
Comments: If this tag is specified, the program will run in Bitmap Mode, using the .bmp file as the source image to paint

<output>filename</output>
Contained-in: painter
Contents: filename: the root name for the output file
Comments: If this tag is specified, the program will run in output mode. If in Bitmap Mode, it will generate the output as filename.bmp. If in Animation Mode, will generate a series of files named filenamexxxx.bmp

<demo></demo>
Contained-in: painter
Comments: If this tag is specified, the program will run in demo mode.

<texture >…</texture>
Contained-in: Root
Attributes: name: the name must be specified and will be used for all references to this texture
Contains: file
Comments: Creates a texture object linked to a file

<file>filename.extension</file>
Contained-in: texture, object
Contents: filename: references a filename
Comments: As a child to texture, the file must be a 24-bit RGB .bmp file, with dimensions as a power of 2. As a child to object, the file must be an .obj model file, that contains only vertex and face definitions.

<material >…</material>
Contained-in: Root
Attributes: name: the name must be specified and will be used for all references to this material
Contains: diffuse, tref
Comments: Creates a material object which has associated colour and texture

<diffuse>r,g,b</diffuse>
Contained-in: material
Contents: r,g,b: red, green and blue values in the range [0..255]
Comments: Specifies the diffuse colour for a material

<tref >texture_name</tref>
Contained-in: material
Attributes: num: num takes a value in the range [1..6] and specifies which of 6 texture spots to fill
Contents: texture_name: reference name for a texture object
Comments: There are six texture spots in a material. If only texture 1 is specified, then that texture will be mapped linearly to the model. If texture spots 1 & 2 are specified, then those two textures will be mapped, one to faces with a positive normal along the axis, and the other to faces with a negative normal along the axis. The axis is specified in the model object. If all 6 texture spots are specified, then cube mapping is performed. Faces with normals closest to the +x axis are mapped with texture 1, normals closest to the –x axis are mapped to texture 2. +y and –y axis use textures 3 & 4, and +z and –z axis use texture 5 & 6.

<object >…</object>
Contained-in: Root
Attributes: name: the name must be specified and will be used for all references to this object
Contains: file, mref, tmap, poly
Comments: Creates a model object which combines geometry information with a material

<mref>material_reference</mref>
Contained-in: object
Contents: material_reference: reference name for a material object
Comments: Associates a material with a model

<tmap >x,y,z</tmap>
Contained-in: object
Attributes: axis: axis is in the set { ‘x’, ‘-x’, ‘y’, ‘-y’, ‘z’, ‘-z’ }
Contents: x,y,z: floating point values > 0
Comments: the axis specifies that primary axis on which the textures are mapped in either 1 or 2 texture mapping mode. The 6 sided cube map is always along the same axis. The floating point values are scale values for the textures. The longest axis of the object is the base distance, and a scale of 1 will have the texture map along the entire axis. Increasing the scale will cause the texture to repeat more often (a value of 2 will have the texture repeat twice along the base length).

<poly>smooth</poly>
Contained-in: object
Contents: smooth: smooth keyword
Comments: If specified, will have vertex normals calculated based on the average of the connecting face normals to create a smooth surface.

<keyframes>…</keyframes>
Contained-in: Root
Contains: frame, particle
Comments: This wraps all the frames involved in the animation

<frame >…</frame>
Contained-in: keyframes
Attributes: time: time is a positive integer value
Contains: oref
Comments: Time is the tick in 1/1000th of a second for the start of this frame. The frame can contain multiple object references that specify different object properties at this time. Frames must appear in increasing order. Any frame out of order will be dropped. Object positions are interpolated linear between two consecutive frames where both frames have a reference to the object. An object will not be rendered at time t unless it has an assigned position from the frames immediately before and after time t.

<oref >…</oref>
Contained-in: frame
Attributes: name: reference name for a model object
Contains: pos, rot
Comments: References a specific object to perform transformations on. Results are unspecified if multiple orefs in the same frame reference the same model object.

<pos>x,y,z</pos>
Contained-in: oref, particle
Contents: x,y,z: are float valued coordinates
Comments: Specifies a position in world coordinates, will be the origin of a particle system, or the origin of a geometry model

<rot >theta</rot>
Contained-in: oref
Attributes: axis: in the set { ‘x’, ‘y’, ‘z’ }
Contents: theta: a float rotation angle in degrees
Comments: Specifies an absolute rotation, counter-clockwise along the axis. Rotations occur after translation of the object, and in the order x-axis, y-axis, z-axis. If no rotation value is specified for an axis, 0 is assumed.

<particle >…</particle>
Contained-in: keyframes
Attributes: time: time is a positive integer value
Contains: pos, velocity, accel, color
Comments: This is a particle system for a 2 stage firework. The 1st stage has 5 particles, which have velocity on an about 20 degree variation from the initial velocity. After 3 seconds, the 5 particles explode into 60 particles each, traveling randomly outwards along the sphere from the ending point of the initial particle. These particles last for at most 4 seconds.

<velocity>x,y,z</velocity>
Contained-in: particle
Contents: x, y, z: float vector coordinates
Comments: specifies an initial velocity vector for a particle system

<accel>a</accel>
Contained-in: particle
Contents: a: float value acceleration
Comments: the acceleration factor, if positive, particles will increase speed, if negative, particles will slow down

<color>r,g,b</color>
Contained-in: particle
Contents: r,g,b: colour component values in the range [0..255]
Comments: specifies the initial colour of the fireworks

<ps></ps>
Contained-in: painter
Comment: Turns pixel shaders on

<bparam>T,max,min</bparam>
Contained-in: painter
Contents: T: Threshold value integer in the range [0..100]
    max: maximum brush stroke length, type unsigned integer
    min: minimum brush stroke length, type unsigned integer
Comment: These values are used to change the brush stroke parameters. Default values are 25, 8, 3

<cpos>x,y,z</cpos>
Contained-in: painter
Contents: x,y,z: float coordinates
Comment: Sets the position of the camera in world coordinates. Camera is looking down -z axis