RFC: Gimzo/Immediate Mode

[garrynewman]

Between the office move I've been trying to push this API forward. This is how we intend to support gimzos in editor view - and it should work in game in the Sandbox Game and for effects etc..

I want to get initial impressions of the API and welcome suggestions on renaming and refactoring.

Setup

To setup you need to create an "instance". This holds all the input and state data. It needs to be tied to a SceneWorld and a SceneCamera to function.

SceneInstance = new Scene.Instance( Camera.World );

Then all you have to do is run the SceneInstance loop..

SceneInstance.FirstPersonCamera( Camera, RenderCanvas );
SceneInstance.UpdateInputs( Camera, RenderCanvas );

using ( SceneInstance.Push() )
{
	RunTheLoop();

}

The Loop

In all likelyhood the end developer will never actually do any of the setup and running the loop. They'll just be calling the Scene functions.

During the loop SceneInstance isn't referenced at all. That's private to the implementation. Something like a Scene Editor or a Prefab Editor would implement the SceneInstance - and everything else would happen inside.

Drawing a model

Simple example, here's how you draw a model

Scene.Draw.Color = Color.White;
Scene.Draw.Model( "models/editor/playerstart.vmdl" );

Transforms

You can change the current transform in which the draw takes place like this

using ( Scene.Scope( "Object67", new Transform( position ) ) )
{
	Scene.Draw.Color = Color.White;
	Scene.Draw.Model( "models/editor/playerstart.vmdl" );		
}

These are scoped, so if you add another scope in that scope, it acts as an offset of that transform, and resets everything back to how it should be afterwards.

Hitboxes

You can add hitboxes in a similar way. Here you can see we define a hitbox, and if it's being hovered over the color turns white. If not, it turns black.

using ( Scene.Scope( "Object67", new Transform( position ) ) )
{
	Scene.Hitbox.BBox( new BBox( 0, 32 ) );

	Scene.Draw.Color = Scene.IsHovered ? Color.White : Color.Black;
	Scene.Draw.Model( "models/editor/playerstart.vmdl" );
}

Gizmos

We will define some common gizmos, like arrows and position and rotation. Like the Draw class, the Gimzo class is extendable so you can add extension methods to it to add new functionality.

using ( Scene.Scope( "ObjectPosition", new Transform( position ) ) )
{
	Scene.Draw.Color = Scene.Colors.Green;
	if ( Scene.Gizmo.Position( "my-arrow", position, out var newPosition ) )
	{
		position = newPosition;
	}

	Scene.Draw.Color = Color.Black;
	Scene.Draw.Text( $"Value: {position.x:n0}, {position.y:n0}, {position.z:n0}", new Transform( Vector3.Down * 50.0f ) );
}

c64dc9ad-0047-49f2-86da-550898e9cf29.mp4

Intentions

There are a few major intentions of this system, a few things I want it to do.

1. Editor Gizmos

We'll be able to draw things around and interact with stuff in the scene view in custom editors like the prefab editor.

2. Game Gizmos

A game like the sandbox mode would be able to draw clientside transient models and gizmos. This is useful for things like a limb poser, which will be able to draw rotation widgets on the joints and allow really easy rotations.

3. Game - Editor Gizmos

Game addons will be able to define entities with special functions that draw their editor representation. So you'd have a static function on your custom entity called DrawEditor or something, which would be called every frame in Hammer (or any other editor) - and that function would be able to draw the model (or sprite, or particle effect, or box etc) and also know if the entity is selected and draw appropriate gizmos for it.

Questions

• Any opinions on the api? Anything look difficult or confusing?
• The name Scene kind of sucks. Should I change it to Gizmo? Any other options?

[Redhacker1]

How about just changing the name to Immediate? This is an immediate mode API. Either way, it looks really good, simple, intuitive and named simply

[LiminalCrab]

If you wanted to shorten it, maybe Live mode would work? Not sure about the implications of the word choice there.
Gizmo is definitely the name to go with IMO, I don't think anyone will struggle with understanding what that is.

[Redhacker1]

Live is an exceptionally poor choice imho. The big thing with the word choice, as for gizmo, I'm not a fan because this is useful for significantly more than just gizmos.

[LiminalCrab]

I agree, what about Instant? Rapid also comes to mind but it implies that there's a delay.

I guess Composition/Compositor would make sense similar to Scene but we run into the same problem as Immediate being a headache to type.

Compo?

[Redhacker1]

Instant and Rapid sits pretty much the same as Live. Immediate mode has less to do with delay, but design philosophy. Composition/Compositor are also completely unrelated and unhelpful. Immediate mode APIs typically do not carry state between frames. Immediate mode APIs require everything from the ground up between frames procedurally.

Maybe Proc for procedural?

[LiminalCrab]

Yeah Composition doesn't make any sense at all. Rapid I thought was alright because it would have to rapidly update to produce the real-time changes we're seeing.

I think Proc makes sense, the only issue people would have is confusing it with process but we doc comments for a reason. I'll vote for Proc.

[suiramdev]

Is there really any point in calling RunTheLoop ourselves? Or maybe it's a placeholder?

[garrynewman]

RunTheLoop() is whatever your editor uses to call the Scene. functions

[Fortune117]

Is something like this planned for hammer? I feel that's where this sort of custom gizmo would really shine (although this might already exist in the tools API, I haven't used that yet)

[Redhacker1]

That's part of the plan and reason for implementing this lol.

[anthonysharpy]

Transforms

I might not be understanding it fully but personally I would prefer this

Scene.Draw.Position = position; // Vector3. Also a separate Rotation field available.
Scene.Draw.Color = Color.White;
Scene.Draw.Model( "models/editor/playerstart.vmdl" );

over this

using ( Scene.Scope( "Object67", new Transform( position ) ) )
{
	Scene.Draw.Color = Color.White;
	Scene.Draw.Model( "models/editor/playerstart.vmdl" );		
}

The implication being that if you wanted to do offsets then you would just do some version of:

Scene.Draw.Position = position + new Vector3(0, 50, 15);

I see some advantage in nesting using statements when it comes to having lots of deeply nested parts that all connect to each other in a complex hierarchy. But in the use case that this is designed for (gizmos etc) I don't know if that would happen very often. I also wonder whether having lots of deeply nested using statements would actually make it harder as opposed to easier to read. But maybe there's just some benefit/some part of the design that I'm not getting?

.Position

It's a bit hard to understand intuitively what this bit of code here does:

if ( Scene.Gizmo.Position( "my-arrow", position, out var newPosition ) )
{
	position = newPosition;
}

I guess this either draws an arrow or updates its position? I think it's because .Position doesn't sound like a method, especially not one that would return a bool.

Performance

It's not mentioned here but there was some talk before about this being usable in-game. Obviously this is my completely uneducated opinion and I have no idea how this is actually being implemented nor how well it performs but my guess would be that this method of rendering is somewhat less efficient when it comes to drawing 3D stuff than the normal way of rendering stuff? If so, my only worry would be that people will think that this is such an easy and convenient way of rendering things that they do it all the time, and everyone's gamemodes will run like garbage. So my only suggestion with regards to that would be that if this is to be useable in-game, it might be a good idea to emphasise the performance limitations (if any - again I don't know) in the documentation?

Other than that very nifty.

[garrynewman]

The transform scopes aren't ideal but they do serve a purpose. Everything you change in the scope is reverted when the scope ends, so color changes and positions don't leak into the next section.

I wish it was as easy as just setting the position and drawing something. The problem is that you might be the child of a child of a child, and you need the positions and rotations of the parents applied to the draw, then you need your position in local coords instead of global coords.

Position - agreed - I'll review all of these

Performance isn't really a problem. It's not 100% optimal but it's not total dog shit like you'd imagine.

[anthonysharpy]

hmm i guess when you get stuff like colours involved it starts to make more sense because it'd be annoying to have to reset those all the time. and when you start adding rotations on top of scaling on top of positions on top of rotations i guess it's not as easy as just doing vector1 + vector2. although perhaps it could be possible to do it either way (with or without the usings)? but not sure if that just adds unnecessary complexity.

glad to hear that the performance is good!

[kouta-kun]

Does this have something along the lines of the ModelBuilder class? I figure this might be good for terrain entities if performance is good enough, using some sort of camera clipping to only render the visible parts of the terrain mesh and generate it at run time, so having something like ModelBuilder where I can just throw raw polygons would be great
EDIT: Also sort of off-topic but are there plans to make some sort of IMGUI-style library for UIs too?