added amb1424 - hudtext functions for mods that support them

--HG--
extra : convert_revision : svn%3A39bc706e-5318-0410-9160-8a85361fbb7c/trunk%401921

plugins/include/halflife.inc

@@ -353,21 +353,162 @@ stock PrintHintTextToAll(const String:format[], any:...)
  * Shows a VGUI panel to a specific client.
  *
  * @param client		Client index.
- * @param name			Panel type name (Check viewport_panel_names.h to see a list of some panel names).
- * @param Kv			KeyValues handle with all the data for the panel setup (Depends on the panel type and may be unused).
+ * @param name			Panel type name (Check viewport_panel_names.h to see a list of 
+ *						some panel names).
+ * @param Kv			KeyValues handle with all the data for the panel setup (Depends 
+ *						on the panel type and may be unused).
  * @param show			True to show the panel, or false to remove it from the client screen.
  * @noreturn
  * @error				If the client is not connected an error will be thrown.
  */
 native ShowVGUIPanel(client, const String:name[], Handle:Kv=INVALID_HANDLE, bool:show=true);
 
+/**
+ * Creates a HUD synchronization object.  This object is used to automatically assign and 
+ * re-use channels for a set of messages.  
+ *
+ * The HUD has a hardcoded number of channels (usually 6) for displaying 
+ * text.  You can use any channel for any area of the screen.  Text on 
+ * different channels can overlap, but text on the same channel will 
+ * erase the old text first.  This overlapping and overwriting gets problematic.
+ *
+ * A HUD synchronization object automatically selects channels for you based on 
+ * the following heuristics:
+ *  - If channel X was last used by the object, and hasn't been modified again, 
+ *    channel X gets re-used.
+ *  - Otherwise, a new channel is chosen based on the least-recently-used channel.
+ *
+ * This ensures that if you display text on a sync object, that the previous text 
+ * displayed on it will always be cleared first.  This is because your new text 
+ * will either overwrite the old text on the same channel, or because another 
+ * channel has already erased your text.
+ *
+ * Note that messages can still overlap if they are on different synchronization 
+ * objects, or they are displayed to manual channels.
+ *
+ * These are particularly useful for displaying repeating or refreshing HUD text, in 
+ * addition to displaying multiple message sets in one area of the screen (for example, 
+ * center-say messages that may pop up randomly that you don't want to overlap each 
+ * other).
+ *
+ * @return				New HUD synchronization object.
+ *						The Handle can be closed with CloseHandle().
+ *						If HUD text is not supported on this mod, then 
+ *						INVALID_HANDLE is returned.
+ */
+native Handle:CreateHudSynchronizer();
+
+/**
+ * Sets the HUD parameters for drawing text.  These parameters are stored 
+ * globally, although nothing other than this function and SetHudTextParamsEx 
+ * modify them.
+ *
+ * You must call this function before drawing text.  If you are drawing 
+ * text to multiple clients, you can set the parameters once, since 
+ * they won't be modified.  However, as soon as you pass control back 
+ * to other plugins, you must reset the parameters next time you draw.
+ *
+ * @param x				x coordinate, from 0 to 1.  -1.0 is the center.
+ * @param y				y coordinate, from 0 to 1.  -1.0 is the center.
+ * @param holdTime		Number of seconds to hold the text.
+ * @param r				Red color value.
+ * @param g				Green color value.
+ * @param b				Blue color value.
+ * @param a				Alpha transparency value.
+ * @param effect 		0/1 causes the text to fade in and fade out.
+ *						2 causes the text to flash[?].
+ * @param fxTime		Duration of chosen effect (may not apply to all effects).
+ * @param fadeIn		Number of seconds to spend fading in.
+ * @param fadeOut		Number of seconds to spend fading out.
+ * @noreturn
+ */
+native SetHudTextParams(Float:x, Float:y, Float:holdTime, r, g, b, a, effect = 0,
+						Float:fxTime=6.0, Float:fadeIn=0.1, Float:fadeOut=0.2);
+						
+/**
+ * Sets the HUD parameters for drawing text.  These parameters are stored 
+ * globally, although nothing other than this function and SetHudTextParams
+ * modify them.
+ *
+ * This is the same as SetHudTextParams(), except it lets you set the alternate 
+ * color for when effects require it.  
+ *
+ * @param x				x coordinate, from 0 to 1.  -1.0 is the center.
+ * @param y				y coordinate, from 0 to 1.  -1.0 is the center.
+ * @param holdTime		Number of seconds to hold the text.
+ * @param color1		First color set, array values being [red, green, blue, alpha]
+ * @param color2		Second color set, array values being [red, green, blue, alpha]
+ * @param effect 		0/1 causes the text to fade in and fade out.
+ *						2 causes the text to flash[?].
+ * @param fxTime		Duration of chosen effect (may not apply to all effects).
+ * @param fadeIn		Number of seconds to spend fading in.
+ * @param fadeOut		Number of seconds to spend fading out.
+ * @noreturn
+ */
+native SetHudTextParamsEx(Float:x, Float:y, Float:holdTime, color1[4], 
+						  color2[4]={255,255,255,0}, effect = 0, Float:fxTime=6.0, 
+						  Float:fadeIn=0.1, Float:fadeOut=0.2);
+
+/**
+ * Shows a synchronized HUD message to a client.  
+ *
+ * As of this writing, only TF, HL2MP, and SourceForts support HUD Text.
+ *
+ * @param client		Client index to send the message to.
+ * @param sync			Synchronization object.
+ * @param message		Message text or formatting rules.
+ * @param ...			Message formatting parameters.
+ * @return				-1 on failure, anything else on success.
+ *						This function fails if the mod does not support it.
+ * @error				Client not in-game, or sync object not valid.
+ */
+native ShowSyncHudText(client, Handle:sync, const String:message[], any:...);
+
+/**
+ * Clears the text on a synchronized HUD channel. 
+ *
+ * This is not the same as sending "" because it guarantees that it won't 
+ * overwrite text on another channel.  For example, consider the scenario: 
+ *
+ * 1. Your synchronized message goes to channel 3.
+ * 2. Someone else's non-synchronized message goes to channel 3.
+ *
+ * If you were to simply send "" on your synchronized message, 
+ * then someone else's text could be overwritten.
+ *
+ * @param client		Client index to send the message to.
+ * @param sync			Synchronization object.
+ * @noreturn
+ * @error				Client not in-game, or sync object not valid.
+ */
+native ClearSyncHud(client, Handle:sync);
+
+/**
+ * Shows a HUD message to a client on the given channel.
+ *
+ * As of this writing, only TF, HL2MP, and SourceForts support HUD Text.
+ * 
+ * @param client		Client index to send the message to.
+ * @param channel		A channel number.
+ *						If -1, then a channel will automatically be selected 
+ *						based on the least-recently-used channel.  If the 
+ *						channel is any other number, it will be modulo'd with 
+ *						the channel count to get a final channel number.
+ * @param message		Message text or formatting rules.
+ * @param ...			Message formatting parameters.
+ * @return				-1 on failure (lack of mod support).
+ *						Any other return value is the channel number that was 
+ *						used to render the text.
+ */
+native ShowHudText(client, channel, const String:message[], any:...);
+
 /**
  * Shows a MOTD panel to a specific client.
  *
  * @param client		Client index.
  * @param title			Title of the panel (printed on the top border of the window).
  * @param msg			Contents of the panel, it can be treated as an url, filename or plain text
- *				  depending on the type parameter (WARNING: msg has to be 192 bytes maximum!)
+ *				 		depending on the type parameter (WARNING: msg has to be 192 bytes maximum!)
  * @param type			Determines the way to treat the message body of the panel.
  * @noreturn
  * @error				If the client is not connected an error will be thrown.