# Hudbot's ScriptGL documentation

Quick Links

- Using ScriptGL
- Textures & Fonts
- ScriptGL Function List
- ScriptGL Functions
- ScriptGL Extensions

## ScriptGL

ScriptGL is a hudbot extension which allows you to use a subset of OpenGL commands from Tribes Script; It also implements a few custom OpenGL commands for textures and fonts.

### Using ScriptGL

Drawing with ScriptGL is only allowed inside special callback functions. Currently only the playGui GUI is supported so that is where your drawing will have to take place. ScriptGL will call ScriptGL::playGui::onPreDraw( %dimensions ) and ScriptGL::playGui::onPostDraw( %dimensions ) before and after the playGui is rendered, allowing you to draw under or over the default HUDs. %dimensions will hold the resolution of the screen in the form of "width height".

    function ScriptGL::playGui::onPreDraw( %dimensions ) {
    	glDisable( $GL_TEXTURE_2D );
    	glColor4ub( 255, 255, 255, 128 );
    	glBegin( $GL_TRIANGLES );
    		glVertex2i( 40, 40 );
    		glVertex2i( 60, 20 );
    		glVertex2i( 80, 40 );
    	glEnd( );
    	...
    }

    function ScriptGL::playGui::onPostDraw( %dimensions ) {
    	...
    }

Since the Tribes Scripting engine is fairly slow, calling these functions once a frame will bog you down quickly if you are doing anything non-trivial. To combat this, ScriptGL will only call the onDraw functions every $ScriptGL::Latency milliseconds (default 100, i.e. 10 times a second). Since there obviously needs to be something displayed in the interim, the onDraw OpenGL calls are compiled in to an intermediate bytecode so your HUDs will be "carbon copied", so to speak, until the next update.

A setting of 15 should be the absolute lowest interval you would need, being slightly higher than 60 times a second. If you are not displaying anything that requires constant updating, a large value such as 1000 (once every second) would be good. After a certain point the overhead of the script calls evaporates and higher latencies have no effect.

### Textures & Fonts

ScriptGL can use any TrueType font a) available to Windows or b) in the "Hudbot/Fonts" directory. All .ttf files in "Hudbot/Fonts" are temporarily loaded to Windows using AddFontResource when Hudbot is started so you may distribute non-standard fonts without requiring the user to manually install them. Fonts may not be zipped.

ScriptGL textures (used by glBindTexture, glDrawTexture, and glGetTextureDimensions) are stored in "Hudbot/ScriptGL". They may be in subdirectories or zipped, but path names are not used when loading textures. Files not in zips will take precedence over zipped files, but no guarantee is made if multiple files with the same name are present in multiple directories and/or zips.

Note: Fonts and textures will be garbage collected if they are not used for 30 seconds. "Using" means calling glBindTexture, glDrawTexture, or glSetFont. The current font and texture are not saved between onDraw calls, i.e. even if you are only using a single font you still need to use glSetFont each onDraw call.

### ScriptGL Function List

- glBegin( mode )
- glBindTexture( texture )
- glBlendFunc( sfactor, dfactor )
- glColor4ub( r, g, b, a )
- glDisable( cap )
- glDrawString( x, y, string )
- glDrawTexture( texture, mode, x, y, [scale_x], [scale_y], [radians] )
- glEnd( )
- glGetStringDimensions( string )( )
- glGetTextureDimensions( texture )
- glRectangle( x, y, width, height )
- glRescanTextureDirectory( )
- glSetFont( font, pixel_height, [render_mode], [glow_radius] )
- glTexCoord2f( x, y )
- glTexEnvi( mode )
- glVertex2i( x, y )

### ScriptGL Functions

The following ScriptGL functions behave like their OpenGL counterparts. Documenation should be fairly easy to find for them if you need more information

- glBegin( mode )
  - $GL_POINTS
  - $GL_LINES
  - $GL_LINE_LOOP
  - $GL_LINE_STRIP
  - $GL_TRIANGLES
  - $GL_TRIANGLE_STRIP
  - $GL_TRIANGLE_FAN
  - $GL_QUADS
  - $GL_QUAD_STRIP
  - $GL_POLYGON
- glBlendFunc( sfactor, dfactor )
  - $GL_ZERO
  - $GL_ONE
  - $GL_SRC_COLOR
  - $GL_ONE_MINUS_SRC_COLOR
  - $GL_SRC_ALPHA
  - $GL_ONE_MINUS_SRC_ALPHA
  - $GL_SRC_ALPHA_SATURATE
  - $GL_DST_COLOR
  - $GL_ONE_MINUS_DST_COLOR
  - $GL_DST_ALPHA
  - $GL_ONE_MINUS_DST_ALPHA
- glColor4ub( r, g, b, a )
- glEnd( )
- glTexCoord2f( x, y )
- glTexEnvi( mode )
  - $GL_DECAL
  - $GL_MODULATE
  - $GL_REPLACE
  - $GL_BLEND

  Note: The trick to drawing colored/transparent textures (even when the source texture is fully opaque) is glTexEnvi( $GL_MODULATE ) followed by glColor4ub( r, g, b, a ). Using glTexEnvi( $GL_REPLACE ) will draw the texture without applying any settings from glColor4ub.

- glVertex2i( x, y )
- glDisable( cap ) is the same as in OpenGL except the only supported cap is $GL_TEXTURE_2D. You will only need this if you want to draw non-texture primitives. glDrawTexture and glBindTexture will enable $GL_TEXTURE_2D for you automatically so there is no need to include support for glEnable.

      glDisable( $GL_TEXTURE_2D );

  - $GL_TEXTURE_2D
- glBindTexture( texture ) takes a texture file name, enables $GL_TEXTURE_2D, and binds the texture to OpenGL. Use this when you need to manually specify texture or vertex coordinates. Ex:

      glTexEnvi( $GL_REPLACE );
      glBindTexture( "mypic.tga" );
      glBegin( $GL_QUADS );
      	glTexCoor2f( 0, 0 ); glVertex2i( 0, 0 );
      	glTexCoor2f( 1, 0 ); glVertex2i( 100, 0 );
      	glTexCoor2f( 1, 1 ); glVertex2i( 100, 100 );
      	glTexCoor2f( 0, 1 ); glVertex2i( 0, 100 );
      glEnd( );

### ScriptGL Extensions

- glDrawString( %x, %y, %string )

  > Draws %string with the current font at the specified position. String formatting is limited to "\n" to move to the next line and "<RR GG BB AA>" for color formatting. Color formatting is not required, so you may use a glColor4ub call before glDrawString if you won't need to change colors mid-string. Ex:

  >     glDrawString( 100, 100, "<ff000080>This string is red\nWith half transparency" );

  >     Or

  >     glColor4ub( 255, 0, 0, 128 );
  >     glDrawString( 100, 100, "This string is red\nWith half transparency" );

  > glDrawString modifies the following OpenGL states that you will need to reset if you require different settings after the call to glDrawString:

  >     glEnable( GL_TEXTURE_2D );
  >     glBlendFunc( GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA );
  >     glTexEnvi( GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_MODULATE );

- glDrawTexture( %texture, %mode, %x, %y, [%scale_x], [%scale_y], [%radians] )

  > This is a shortcut function which saves you from having to manually bind the texture and specify the texture coordinates / vertex positions manually. The built in modes should cover most of the situations you will commonly encounter when drawing textures:

  > - $GLEX_DRAW: Draws the texture with the topleft corner at %x, %y.
  > - $GLEX_CENTERED: Draws the texture with it's center on %x, %y.
  > - $GLEX_SCALED: Draws the texture with the topleft corner at %x, %y and scaled by %scale_x, %scale_y (if present).
  > - $GLEX_ROTATED: Draws the texture with it's center at %x, %y, scaled by %scale_x, %scale_y (if present), and rotated %radians radians (if present).

  > Ex:

  >     glDrawTexture( "mypic.tga", $GLEX_DRAW, 100, 100 );
  >     // Centered at 100, 100
  >     glDrawTexture( "mypic.tga", $GLEX_CENTERED, 100, 100 );
  >     // Scaled 1.5x
  >     glDrawTexture( "mypic.tga", $GLEX_SCALED, 100, 100, 1.5, 1.5 );
  >     // Centered at 100, 100, Scaled 2x, Rotated 1.57 rads
  >     glDrawTexture( "mypic.tga", $GLEX_ROTATED, 100, 100, 2, 2, 1.57 );

  > glDrawTexture modifies the following OpenGL states that you will need to reset if you require different settings after the call to glDrawTexture:

  >     glEnable( GL_TEXTURE_2D );

  > %mode Constants:

  > - $GLEX_DRAW
  > - $GLEX_CENTERED
  > - $GLEX_ROTATED
  > - $GLEX_SCALED

- glGetStringDimensions( %string )

  > Returns the dimensions for the string using the current font in the form of "Width Height". e.g. glGetStringDimensions( "test string\n2nd line" ) returns "182 36".

- glGetTextureDimensions( %texture )

  > Returns the dimensions for the texture in the form of "Width Height". If the texture is not found, "0 0" is returned. e.g. glGetTextureDimensions( "mypic.tga" ) returns "256 128".

- glRectangle( %x, %y, %width, %height )

  > Draws a rectangle at %x, %y which is %width pixels long and %height pixels tall.

- glRescanTextureDirectory( )

  > Forces ScriptGL to free all of it's textures and rescan "Hudbot/ScriptGL" for new textures. Use this if you alter a texture and would like it to be reloaded.

  > Note: You cannot replace edit or replace .zip files while Tribes is running so you can only replace non-zipped files.

- glSetFont( %font, %pixel_height, [%render_mode], [%glow_radius] )

  > Sets the active font to %font with a height of %pixel_height. %font is the typeface name of the TrueType font you would like to use (as found in the font browers for programs such as Photoshop and Paint Shop Pro). %render_mode may be either $GLEX_PIXEL for raw rendering or $GLEX_SMOOTH for anti-aliased rendering (default is $GLEX_SMOOTH). If Windows cannot find the specified font, the default system font will be used.

  > %glow_radius adds a "bloom" effect to the font characters. 0 is no glow effect, 2 is the smallest radius you can choose and 16 is the largest. Processing time increases enormously as the glow radius increases ( height * width * ( glow_radius + 1 ) * 2 pixels are processed for each character ).

  > Note: Font characters are rendered on demand so nothing is created until you call glDrawString. In addition, when a font has been unused for 30 seconds (i.e. glSetFont has not been called for the font), it will be garbage collected, allowing you to freely create fonts without fear of them piling up in memory. You may create and use as many fonts as you like, memory permitting. Ex:

  >     // Times New Roman, 48px, Anti-Aliased, 7 pixel glow
  >     glSetFont( "Times New Roman", 48, $GLEX_SMOOTH, 7 );
  >     // Only the letters 'T', 'e', 's', and 't' will be rendered and uploaded to video card memory
  >     glDrawString( 100, 100, "Test" );
  >     // The letter '2' will be rendered and uploaded to video card memory, the others are cached
  >     glDrawString( 100, 200, "Test2" );
  >     // Verdana, 10px, No Anti-Aliasing, no pixel glow
  >     glSetFont( "verdana", 10, $GLEX_PIXEL );
  >     // 'T', 'e', 's', 't', and '2' will now be rendered for Verdana
  >     glDrawString( 300, 400, "Test2" );
  >     // If we do not glSetFont either font for 30 seconds, they will be
  >     // garbage collected

  > %render_mode Constants:

  > - $GLEX_PIXEL
  > - $GLEX_SMOOTH