Changes between Version 1 and Version 2 of GUI_-_Sprites


Ignore:
Timestamp:
May 7, 2015, 10:31:39 PM (4 years ago)
Author:
s0600204
Comment:

Remove deprecated "multiply_color" effect, adds "color:" and "grayscale:" sprite shortcuts

Legend:

Unmodified
Added
Removed
Modified
  • GUI_-_Sprites

    v1 v2  
    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>''.
     1A sprite is an object consisting of a number of properties that define an image which be used by the GUI. Many sprites are defined in {{{<sprite1.xml>}}}.
    22
    33The 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.
     
    5454}}}
    5555
    56 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.
     56We 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.
    5757
    5858== sprite ==
    5959
    60 Within <sprites></sprites>, you can define as many <sprite></sprite>s as you wish.
    61 
    62 === ''name'' ===
    63 
    64 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.
     60Within {{{<sprites></sprites>}}}, you can define as many {{{<sprite></sprite>}}}s as you wish.
     61
     62=== name ===
     63
     64Each 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.
    6565
    6666=== image ===
     
    7171
    7272==== backcolor ====
    73  * default: ?
     73 * default: "0 0 0 0"
    7474 * value: color
    7575
    76 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.
     76Regular 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.
    7777
    7878==== border ====
    7979 * default: "false"
    80  * value: bool "(true|false)"
    81 
    82 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.
    83 
    84 If ''false'', no border is displayed.
     80 * value: bool string "(true|false)"
     81
     82If 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.
     83
     84If {{{"false"}}}, no border is displayed.
    8585
    8686==== bordercolor ====
    87  * default: ?
     87 * default: "0 0 0 0"
    8888 * value: color
    8989
    90 If ''border'' is ''true'', this property indicates the RGB colour of the border (see GUIColor).
     90If {{{border}}} is {{{"true"}}}, this property indicates the RGB colour of the border (see GUIColor).
    9191
    9292Useless if border is not true.
    9393
    94 ==== [wiki:cell_size] ====
    95 
    96 Its 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.
    97 
    98 With this method, we can keep all 64x64 Celtic entity portraits in one sprite, for example, and reference the individual cells.
    99 
    100 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:
     94==== cell_size ====
     95
     96It'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.
     97
     98With this method, we can keep multiple identically-sized icons in one sprite, for example, and reference the individual cells.
     99
     100To 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:
    101101
    102102{{{
     
    110110}}}
    111111
    112 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.
    113 
    114 ==== <font color="red">delta_z</font> ====
    115 
    116 <font color="red">Replaced with ''z_level''? Confirm.</font>
     112The 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.
     113
     114==== delta_z ====
     115
     116Replaced with {{{z_level}}}? Confirm.
    117117
    118118==== real_texture_placement ====
     
    129129}}}
    130130
    131 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:
     131To 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:
    132132
    133133{{{
     
    148148Indicates size and position of the image relative to object size.
    149149
    150 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.
     150For 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.
    151151
    152152==== texture ====
     
    154154 * value: name
    155155
    156 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.
     156The 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, .png and .dds.
    157157
    158158==== texture_size ====
     
    160160 * value: client area
    161161
    162 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.
    163 
    164 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''.
    165 
    166 ==== <font color="green">z_level</font> ====
     162Where 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.
     163
     164Note 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}}}.
     165
     166==== z_level ====
    167167 * default: 0
    168168 * value: int
    169169
    170 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.
     170This 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.
    171171
    172172=== Skip a step ===
    173173
    174 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.
    175 
    176 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:
     174==== Single Texture ====
     175
     176When 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.
     177
     178Because 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 {{{sprite}}} property:
    177179
    178180{{{
     
    183185
    184186{{{
    185   <sprite name="new_name">
     187  <sprite name="single_texture">
    186188          <image texture="texture-from-texture-database"
    187189                 size="0 0 100% 100%"
     
    191193}}}
    192194
     195==== Single Texture, Grayscale ====
     196
     197The above can be extended further with the addition of {{{grayscale:}}} after {{{stretched:}}} but before the texture's name. For instance:
     198
     199{{{
     200  sprite="stretched:grayscale:example_texture.jpg"
     201}}}
     202
     203Is the equivalent of:
     204
     205{{{
     206  <sprite name="grayscale_single_texture">
     207          <effect grayscale=""/>
     208           
     209          <image texture="texture-from-texture-database"
     210                 size="0 0 100% 100%"
     211                 texture_size="0 0 100% 100%"
     212          />
     213  </sprite>
     214}}}
     215
     216==== Block Colour ====
     217
     218Under certain circumstances, you might want a sprite to just be a single block colour, such as a unit's health or capture bars. This can most easily be achieved by using {{{color:}}} at the start of an object's {{{sprite}}} property, and following it up with a colour specified using the same syntax as the {{{backcolor}}} sprite syntax above:
     219
     220{{{
     221  sprite="color: 255 0 0"
     222}}}
     223
     224The above is perfectly valid and creates an entirely red, opaque block, the equivalent of:
     225
     226{{{
     227  <sprite name="block_colour">
     228          <image
     229              backcolor="255 0 0"
     230          />
     231  </sprite>
     232}}}
     233
     234'''Scripting Tip''': In JS, you can use {{{rgbToGuiColor()}}} (found in common/functions_utility.js) to translate from a {{{{"r":64, "g":64, "b":64} }}} type object to a {{{"64 64 64"}}} string.
     235
    193236=== effect ===
    194237
    195 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).
    196 
    197 Effects are specified in the <effect/> tag, which must always appear before any <image>s in a <sprite> declaration.
     238Effects 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 Gimp, PhotoShop or any other image editor).
     239
     240Effects are specified in the {{{<effect/>}}} tag, which '''must always''' appear before any {{{<image>}}}s in a {{{<sprite>}}} declaration.
    198241
    199242{{{
    200243  <!-- Creates a stretched texture that's bled of all colour (grayscale), and brighter than the source image. -->
    201244  <sprite name="new_name_over">
    202           <effect add_color=�42 42 42 0�
     245          <effect add_color="42 42 42 0"
    203246                  grayscale=""
    204247          />
     
    212255==== add_color ====
    213256
    214 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.
    215 
    216 ==== multiply_color ====
    217 
    218 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.
    219 
    220 Due to an OpenGL clamping restriction, components can never be > 255, so ''multiply_color'' cannot make an image brighter (though ''add_color'' can).
    221 
    222 ==== <font color="green">grayscale</font> ====
     257The 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.
     258
     259==== grayscale ====
    223260
    224261This effect removes all colour from the sprite, replacing colours with shades of gray. This is particularly useful for disabled versions of sprites.