LogoLogo
  • Gum Tool
    • Introduction
    • Setup
      • Running from Source
    • Showcase
    • Tutorials and Examples
      • Intro Tutorials
        • 1 - The Basics
        • 2 - Variables Tab
        • 3 - Files
        • 4 - Components
        • 5 - Exposing Variables
        • 6 - Parent
        • 7 - States
        • 8 - State Categories
      • Animation Tutorials
        • 1 - Introduction to Animation
        • 2 - Creating an Animation
        • 3 - Playing Animations inside other Animations
        • 4 - Combining Multiple Categories
      • Examples
        • Bottom-Up Stack
        • Centering
        • Custom NineSlice
        • Health Bar
        • Padding
    • Gum Elements
      • General Properties
        • Alpha
        • Base Type (Inheritance)
        • Blend
        • Clips Children
        • Has Events
        • Height Units
        • Ignored By Parent Size
        • Locked
        • Max Height
        • Max Width
        • Min Height
        • Min Width
        • Order
        • Parent
        • Rotation
        • Visible
        • Variable References
        • Width Units
        • X
        • X Origin
        • X Units
        • Y
        • Y Origin
        • Y Units
      • Behaviors
        • Default Implementation
      • Circle
      • ColoredRectangle
      • Component
        • Default Child Container
      • Container
        • Children Layout
        • Contained Type
        • Is Render Target
        • Stack Spacing
        • Wraps Children
      • NineSlice
        • Blend
        • Custom Frame Texture Coordinate Width
        • Texture Address
        • Texture Left
        • Texture Top
      • Polygon
        • Points
      • Skia Standard Elements
        • General Properties
          • Has Dropshadow
          • Is Filled
          • Use Gradient
        • Arc
          • Start Angle
          • Sweep Angle
          • Thickness
        • Canvas
        • ColoredCircle
        • LottieAnimation
        • RoundedRectangle
          • Corner Radius
        • Svg
      • Sprite
        • Color
        • Source File
        • Texture Address
        • Wrap
      • States
        • Categories
      • Text
        • Blue
        • Color
        • Font
        • Font Scale
        • Font Size
        • Green
        • Is Bold
        • Is Italic
        • MaxLettersToShow
        • Outline Thickness
        • Red
        • Text
        • Text Overflow Horizontal Mode
        • Text Overflow Vertical Mode
        • Use Custom Font
        • Use Font Smoothing
    • Project Tab
    • Code Tab
      • Runtime Generation Details
      • Generation Scope
      • Inheritance Location
      • Is CodeGen Plugin Enabled
      • Show CodeGen Preview
    • Localization
    • Menu
      • Content
      • Project Properties
    • Plugins
      • AddAndRemoveVariablesForType
      • AddMenuItem
      • Export
      • Setting Up Post Build Events
    • Variables
      • Add Variable
    • Bitmap font generator (.fnt)
    • Upgrading
      • Migrating 2025 April 27 to May 28
      • Breaking Changes
        • Removal of Variable Spaces
  • Code
    • Gum Code Reference
      • AnimationRuntime
      • BitmapCharacterInfo
      • BitmapFont
      • Camera
      • CircleRuntime
      • ColoredRectangleRuntime
      • Component Runtimes
      • ContainerRuntime
      • Cursor
      • Gum Class Overview
      • DataUiGrid
        • Reflection
        • Categories
      • ElementSave
        • ToGraphicalUiElement
      • GraphicalUiElement
        • Absolute Values
        • AddToManagers
        • AnimateSelf
        • ApplyState
        • BlendState
        • CanvasHeight
        • CanvasWidth
        • Children
        • ContainedElements
        • Font Values
        • GetAbsoluteHeight
        • GetAbsoluteWidth
        • GetChildByNameRecursively
        • GetFrameworkElementByName
        • IsAllLayoutSuspended
        • Parent
        • RemoveFromManagers
        • UpdateLayout
      • GumProjectSave
      • IDataUi
      • InstanceMember
      • InstanceSave
      • InteractiveGue
        • CurrentInputReceiver
        • RaiseChildrenEventsOutsideOfBounds
        • RollOverBubbling
      • IPositionedSizedObject
      • Layer
      • NineSliceRuntime
      • RectangleRuntime
      • Renderer
        • SinglePixelTexture
      • SelectedState
      • SpriteRenderer
        • LastFrameDrawStates
      • SpriteRuntime
        • TextureAddress
        • TextureHeight
        • TextureLeft
        • TextureTop
        • TextureWidth
      • TextRuntime
        • Color
        • FontScale
        • FontSize
        • HorizontalAlignment
        • Text Wrapping
        • VerticalAlignment
      • VariableSave
    • FNA
    • Kni
    • Meadow
    • MonoGame
      • Setup
        • Linking Game Project to Source (Optional)
      • Tutorials
        • Gum Project Forms Tutorial
          • Setup
          • Gum Screens
          • Common Component Types
          • Styling
          • Multiple Screens
        • Code-Only Gum Forms Tutorial
          • Setup
          • Forms Controls
          • ListBox Items
          • Input in Forms
        • [Deprecated] Gum Project (.gumx) Tutorial
          • Setup
          • Gum Screens
          • Gum Forms
          • Customizing Forms
          • Strongly Typed Components Using Code Generation
          • Multiple Screens
      • Setup for GumBatch (Optional)
      • Loading a Gum Project (Optional)
      • async Programming
      • Custom Runtimes
      • GumBatch
      • Gum Forms
        • Binding (ViewModels)
        • Controls
          • Button
          • CheckBox
          • FrameworkElement
            • BindingContext
            • IsEnabled
            • IsFocused
            • ModalRoot and PopupRoot
            • SetBinding
          • Label
          • ListBox
          • ListBoxItem
          • MenuItem
          • PasswordBox
          • RadioButton
          • ScrollViewer
            • VerticalScrollBarValue
          • StackPanel
          • Slider
          • TextBox
          • Window
        • Control Customization In Code
          • MenuItem
        • Control Customization in Gum Tool
        • Gamepad Support
        • Keyboard Support
        • Troubleshooting
      • File Loading
      • Resizing the Game Window
      • Known Issues
      • Samples
        • MonoGameGumFormsSample
    • Nez
    • Silk.NET
    • SkiaGum
      • Setup
        • WPF
    • .NET MAUI
      • Setup
Powered by GitBook
On this page
  • Introduction
  • Rendering Strings
  • Rendering TextRuntimes
  • Rendering Parent/Child Hierarchy
  • RenderTargets

Was this helpful?

Edit on GitHub
Export as PDF
  1. Code
  2. MonoGame

GumBatch

PreviousCustom RuntimesNextGum Forms

Last updated 5 months ago

Was this helpful?

Introduction

GumBatch is an object which supports immediate mode rendering, similar to MonoGame's SpriteBatch. GumBatch can support rendering text with DrawString as well as any IRenderableIpso.

For information on getting your project set up to use GumBatch, see the page.

Rendering Strings

GumBatch can be used to render strings directly. This requires a BitmapFont.

The following code renders a string at X = 100, Y=200:

gumBatch.Begin();
gumBatch.DrawString(
    font, 
    "I am at X=100, Y=200",
    new Vector2(100, 200), 
    Color.White);
gumBatch.End();

Multiple strings can be rendered between Begin and End calls:

gumBatch.Begin();
for(int i = 0; i < 10; i++)
{
    gumBatch.DrawString(
        font, 
        $"This is string {i}", 
        new Vector2(0, 20*i), 
        Color.White);

}
gumBatch.End();

DrawString can accept newlines and color the text:

gumBatch.Begin();
    gumBatch.DrawString(
        font, 
        $"This string contains\nnewlines which result in\nthe text rendering over multiple lines",
        new Vector2(20, 20), 
        Color.Purple);
gumBatch.End();

Rendering TextRuntimes

If your text rendering requires more advanced positioning, wrapping, rotation, sizing, and so on, you can use TextRuntime instances.

TextRuntimes can be used in both GumBatch as well as they can be added to the SystemManagers if you use SystemManagers.Draw (retained mode).

The following code shows how to create a TextRuntime instance and render it using GumBatch:

// In Game1 at class scope:
TextRuntime textRuntime;

// In Initialize:
textRuntime = new TextRuntime();
textRuntime.UseCustomFont = true;
textRuntime.CustomFontFile = "Fonts/Font16Jing_Jing.fnt";
textRuntime.Text = 
    "I am an immediate mode TextRuntime. I am really long text which will wrap within the bounds of the TextRuntime";
textRuntime.X = 0;
textRuntime.XUnits = Gum.Converters.GeneralUnitType.PixelsFromMiddle;
textRuntime.XOrigin = HorizontalAlignment.Center;

textRuntime.Y = 0;
textRuntime.YUnits = Gum.Converters.GeneralUnitType.PixelsFromMiddle;
textRuntime.YOrigin = VerticalAlignment.Center;

textRuntime.HorizontalAlignment = HorizontalAlignment.Center;
textRuntime.VerticalAlignment = VerticalAlignment.Center;

textRuntime.Width = 300;
textRuntime.WidthUnits = Gum.DataTypes.DimensionUnitType.Absolute;
textRuntime.Height = 0;
textRuntime.HeightUnits = Gum.DataTypes.DimensionUnitType.RelativeToChildren;

textRuntime.Rotation = 90;

// In Draw:
gumBatch.Begin();
gumBatch.Draw(textRuntime);
gumBatch.End();

Rendering Parent/Child Hierarchy

GumBatch.Draw renders any argument renderable object. If the object has children, then the Draw call performs a hierarchical draw, respecting the parent/child relationship to control draw order.

For example, the following code creates a parent ColoredRectangleRuntime and a child TextRuntime:

Since the Draw call is only called on the Parent, then only the Parent reference is kept at class scope:

// at class scope:
ColoredRectangleRuntime buttonRectangle;

// in initialize:
// It's possible to create a runtime object...
buttonRectangle = new ColoredRectangleRuntime();
buttonRectangle.Width = 128;
buttonRectangle.Height = 32;
buttonRectangle.Color = Color.DarkBlue;
buttonRectangle.X = 0;
buttonRectangle.Y = 100;
// ... and add children to it:
var buttonText = new TextRuntime();
buttonText.Text = "Button text";
buttonText.X = 0;
buttonText.Y = 0;
buttonText.Width = 0;
buttonText.Height = 0;
buttonText.XUnits = Gum.Converters.GeneralUnitType.PixelsFromMiddle;
buttonText.YUnits = Gum.Converters.GeneralUnitType.PixelsFromMiddle;
buttonText.XOrigin = HorizontalAlignment.Center;
buttonText.YOrigin = VerticalAlignment.Center;
buttonText.HorizontalAlignment = HorizontalAlignment.Center;
buttonText.VerticalAlignment = VerticalAlignment.Center;
buttonText.WidthUnits = Gum.DataTypes.DimensionUnitType.RelativeToContainer;
buttonText.HeightUnits = Gum.DataTypes.DimensionUnitType.RelativeToContainer;
buttonRectangle.Children.Add(buttonText);

// Then draw call is only performed on the buttonRectangle - the children 
// (buttonText) are drawn automatically:
gumBatch.Begin();
gumBatch.Draw(buttonRectangle);
gumBatch.End();

RenderTargets

GumBatch can be used to render Gum objects on RenderTarget2Ds, just like regular SpriteBatch calls.

The following code shows how to render on a RenderTarget:

// Assuming MyRenderTarget is a valid render target:
GraphicsDevice.SetRenderTarget(MyRenderTarget);
gumBatch.Begin();
gumBatch.Draw(SomeGumObject);
gumBatch.End();

// now set the render target to null to draw it to screen:
GraphicsDevice.SetRenderTarget(null);
spriteBatch.Draw(MyRenderTarget, new Vector2(0, 0), Color.White);

Note that if you are rendering multiple objects on a render target, the BlendState must be set as to add the transparency. Using the default BlendState may result in alpha being "removed" from the render target when new instances are drawn.

The following shows how to create a BlendState for objects which have partial transpraency and are to be drawn on RenderTargets:

var blendState = new BlendState();

blendState.ColorSourceBlend = BlendState.NonPremultiplied.ColorSourceBlend;
blendState.ColorDestinationBlend = BlendState.NonPremultiplied.ColorDestinationBlend;
blendState.ColorBlendFunction = BlendState.NonPremultiplied.ColorBlendFunction;

blendState.AlphaSourceBlend = Blend.SourceAlpha;
blendState.AlphaDestinationBlend = Blend.DestinationAlpha;
blendState.AlphaBlendFunction = BlendFunction.Add;

halfTransparentRectangle.BlendState = blendState;
Setup for GumBatch
A single text object rendered using DrawString
Multiple DrawString calls between Begin and End
Colored text with newlines
Rendering a TextRuntime in immediate mode with GumBatch
buttonRectangle drawn with its child buttonText