Changes between Initial Version and Version 1 of GUI_-_Sprites

Timestamp:

Feb 23, 2008, 4:18:58 AM (16 years ago)

Author:

trac

Comment:

--

GUI_-_Sprites

@@ +1 @@
+A sprite is an object consisting of a number of properties that define an image which be used by the GUI. Sprites are defined in ''<sprite1.xml>''.
+
+The sprite system is quite complex, but very powerful once understood. An image can consist of a number of textures, arranged in a collage, and they can be placed and tiled in a quite dynamic way. For example, one could create a dialog box with fixed edges, but a resizeable tile inside.
+
+Take the resizeable button illustrated in the image below, for example:
+
+[[Image(http://www.wildfiregames.com/~code/resources/wiki/gui/sprite_example.gif)]]
+
+All the corners have a static size (the size of the border texture), but the length dynamically tiles. The central image also tiles. Here's how we'd define that sprite, assuming that the border's texture is size 20x20:
+
+{{{
+  <sprites>
+      <sprite name="button">
+            <!-- Starting with top left corner continuing in a clockwise manner -->
+            <image texture="t1.jpg"
+                   size="0 0 20 20"
+                   texture_size="0 0 20 20" 
+            />
+            <image texture="t2.jpg" 
+                   size="20 0 100%-20 20"
+                   texture_size="0 0 20 20" 
+            />
+            <image texture="t3.jpg"
+                   size="100%-20 0 100% 20"
+                   texture_size="0 0 20 20" 
+            />
+            <image texture="t4.jpg"
+                   size="100%-20 20 100% 100%-20"
+                   texture_size="0 0 20 20" 
+            />
+            <image texture="t5.jpg"
+                   size="100%-20 100%-20 100% 100%"
+                   texture_size="0 0 20 20" 
+            />
+            <image texture="t6.jpg"
+                   size="20 100%-20 100%-20 100%"
+                   texture_size="0 0 20 20" 
+            />
+            <image texture="t7.jpg"
+                   size="0 100%-20 20 100%"
+                   texture_size="0 0 20 20" 
+            />
+            <image texture="t8.jpg"
+                   size="0 20 20 100%-20"
+                   texture_size="0 0 20 20" 
+            />
+            <!-- middle -->
+            <image texture="t9.jpg"
+                   size="20 20 100%-20 100%-20"
+                   texture_size="0 0 100 100" 
+            />
+      </sprite>
+  </sprites>
+}}}
+
+We just created a sprite with its texture stretched to its every corner with the image stretched to the object�s corners. Within the <sprite> and </sprite> you can have as many <image /> as you like, they are each real sprites; they all together form the entire collage.
+
+== sprite ==
+
+Within <sprites></sprites>, you can define as many <sprite></sprite>s as you wish.
+
+=== ''name'' ===
+
+Each sprite has a unique name. This is referenced by properties such as ''sprite'' and ''sprite_over'' to tell the control to use this sprite as its image under the appropriate circumstances.
+
+=== image ===
+
+The sprite can consist of any number of images, forming a collage. Each image is derived from a single texture.
+
+The image in turn has a number of definable properties:
+
+==== backcolor ====
+ * default: ?
+ * value: color
+
+Regular RGB colour stamp including transparency eg backcolor="255 0 255 50" (see GUIColor). If no ''texture'' property is specified, the area is filled with this colour.
+
+==== border ====
+ * default: "false"
+ * value: bool "(true|false)"
+
+If set to ''true'', the texture's area is surrounded by a border in ''bordercolor'', starting at the edge of the image. As the object's ''buffer_zone'' increases, the border thickens inwards from the edge. 
+
+If ''false'', no border is displayed.
+
+==== bordercolor ====
+ * default: ?
+ * value: color
+
+If ''border'' is ''true'', this property indicates the RGB colour of the border (see GUIColor). 
+
+Useless if border is not true.
+
+==== [wiki:cell_size] ====
+
+It�s often more efficient to put multiple sprites of the same size in a grid, rather than storing each as a separate texture (for example, a series of unit portraits). Although we can reference different areas of a texture and store it in a sprite, each element in a sheet of icons would have to be assigned its own sprite, which would be highly repetitive.
+
+With this method, we can keep all 64x64 Celtic entity portraits in one sprite, for example, and reference the individual cells.
+
+To activate this feature, just add ''cell_size="<cell_width> <cell_height>" (with appropriate numbers for the width and length of each cell) to the <image> attributes to tell the sprite parser the size of the individual cells:
+
+{{{
+  <sprite name="new_name">
+          <image texture="texture-from-texture-database"
+                 cell-size="64 64"
+                 size="0 0 100% 100%"
+                 texture_size="0 0 100% 100%"
+          />
+  </sprite>
+}}}
+
+The GUI control <object>s have a corresponding ''cell_id'' attribute to specify which cell of the sprite they should display at the moment; "0" is the 1st element in the sprite.
+
+==== <font color="red">delta_z</font> ====
+
+<font color="red">Replaced with ''z_level''? Confirm.</font>
+
+==== real_texture_placement ====
+ * default: "0 0 0 0"
+ * value: client area
+
+This is a recent addition to get around the problem of having to '''very''' precisely define objects with a percentage size (eg buttons that should adjust to fit the current resolution, and always take up the same amount of space onscreen). This led to definitions like:
+
+{{{
+  <image texture="ui_pregame_mainmenu_background.png"
+         size="0 0 100% 100%" 
+         texture-size="0 0 100% 133.333333333%"
+  />
+}}}
+
+To get around this, we have the property ''real_texture_placement'', which specifies the size of the '''real''' texture, not the texture file. So the above example becomes:
+
+{{{
+  <image texture="ui_pregame_mainmenu_background.png"
+         real-texture-placement="0 0 1024 768"
+         size="0 0 100% 100%" 
+  /> 
+}}}
+
+This feature could also be used to store several textures in a file and specify a certain area of the source texture and cut out that area as the sprite's texture.
+
+Since it just processes the texture coordinates, it doesn't cut out the texture, so you can't tile a cut out texture, because the rest of the image will be shown too.
+
+==== size ====
+ * default: "0 0 100% 100%"
+ * value: client area
+
+Indicates size and position of the image relative to object size.
+
+For single-textured sprites, it's recommended to leave the size as "0 0 100% 100%", and let the size of the object dictate the size of the sprite.
+
+==== texture ====
+ * default: "null"
+ * value: name
+
+The name and path of the texture file to use as the source image for this texture. A number of file formats are available, including .jpg, .gif and .dds.
+
+==== texture_size ====
+ * default: "0 0 100% 100%"
+ * value: client area
+
+Where the texture should be placed within the image; outside this size it will tile. If set to a percentage (eg "0 0 100% 100%"), it will stretch beyond this size instead of tile.
+
+Note that "0 0 100% 100%" is the default, so if you need a sprite that simply stretches to fit its control object, you don't need to specify ''texture_size''.
+
+==== <font color="green">z_level</font> ====
+ * default: 0
+ * value: int
+
+This is the sprite equivalent of an object's ''z''. Specifying the textures in the right sequence and leaving ''delta_z'' alone should normally be sufficient, but if you want to move a texture up or down the layers of the collage, you can specify its ''delta_z'' value.
+
+=== Skip a step ===
+
+When using sprites it�s very important to know the difference between the sprite name and the texture name. You can�t just go ''sprite="example_texture.jpg'' and expect that to work. You have to setup a sprite with that texture first. 
+
+Because a 100%-stretched single texture sprite is such a regular occurrence, however, there's a template to skip that step and directly reference the texture. You can do that by using ''stretched:'' in the object's ''string='' property:
+
+{{{
+  sprite="stretched:example_texture.jpg"
+}}}
+
+The above is perfectly valid code, the equivalent of:
+
+{{{
+  <sprite name="new_name">
+          <image texture="texture-from-texture-database"
+                 size="0 0 100% 100%"
+                 texture_size="0 0 100% 100%" 
+          />
+  </sprite>
+}}}
+
+=== effect ===
+
+Effects are special features that can be added to a sprite when it is first created. For example, the brightness of all images in a sprite can be altered from their base image so they appear lit (to create an illuminated hover version of a button, for example, without having to create a duplicate texture and alter its brightness in PhotoShop).
+
+Effects are specified in the <effect/> tag, which must always appear before any <image>s in a <sprite> declaration.
+
+{{{
+  <!-- Creates a stretched texture that's bled of all colour (grayscale), and brighter than the source image. -->
+  <sprite name="new_name_over">
+          <effect add_color=�42 42 42 0�
+                  grayscale="" 
+          />
+          <image texture="texture-from-texture-database"
+                 size="0 0 100% 100%"
+                 texture_size="0 0 100% 100%" 
+          />
+  </sprite>
+}}}
+
+==== add_color ====
+
+The add_color effect adds a specified RGB value to the colour value of the sprite. For example, add-color="42 42 42" increases the overall brightness of the sprite when displayed, particularly useful for buttons that illuminate when the cursor hovers over them.
+
+==== multiply_color ====
+
+Similar to ''add_color'', except it multiples each component (where they�re in the range 0-1 rather 0-255); in other words, ''multiply-color'' will always leave black parts black, but brighten other parts, rather like a contrast adjustment. 
+
+Due to an OpenGL clamping restriction, components can never be > 255, so ''multiply_color'' cannot make an image brighter (though ''add_color'' can).
+
+==== <font color="green">grayscale</font> ====
+
+This effect removes all colour from the sprite, replacing colours with shades of gray. This is particularly useful for disabled versions of sprites.