Visportals

written by Fidcal

What are visportals?

Visportals are brushes between areas of a doom map used to avoid unnecessary rendering. Without visportals, the Doom engine would render the entire map even if the player can only see one small area. This would reduce performance and slow the game down.

Visportals determine how far the engine should render from the player's position. When a visportal is in the player's view, the engine tests to see if there is a second visportal viewable from the position of the first. If yes then it tests to see if a third one can be seen from the second one. If the third is not viewable from the first then the engine won't waste time rendering the map beyond it. If it is, then the engine tests for a fourth one and so on. So for example, with a long corridor with lots of 90 degree turns in it and visportals at every bend then the engine will only render the section you are in plus the next section which gradually reveals more of itself as you approach the bend. But as you get near to it and can see further down it to the next bend's visportal then it will render the next one too.

The console command r_showPortals 1 shows visportals as rectangles in-game for testing. A red rectangle is a 'closed' visportal with nothing rendered beyond it. A green rectangle is an 'open' visportal and renders everything beyond it up to the next visportal, and so on. In game, if a visportal does not show as red or green or at all then it ain't working!

The console command r_showtris 2 shows what is currently rendered (as triangular wireframes.) You might also use r_useScissor 0 to show geometry outside the visportal rectangle that Doom still sends to the video card but tells it not to render. This helps performance but even sending it uses processor time so if you can reduce it by adjusting visportal placement so much the better.

How and where to create visportals

Visportals are just brushes with one face covered in visportal texture. That is the operative face. So to create one you just....

• Make a thin rectangular brush like a wall.
• Give the brush: textures > common > nodraw all over.
• Give it textures > editor > visportal to either of the main surfaces facing towards or away from you. It does not matter which except you need to be aware which it is because the visportal will be effective at that one face. (Use Ctrl + Shift + Left Mouse Click on the face in the Dark Radiant camera view to select one face.)

Thickness

The exact thickness is not important to its effectiveness as it will only be effective from its one visportal-textured face anyway but it makes sense to keep it reasonably thin so you can see it clearly in the editor.

Where to place your Visportal

It will eventually be wedged tight like a plug into gaps, doorways, etc. between areas. The four edges of the visportal-textured face of visportals should be completely sealed by or in solid brush that has no gaps. This is true even if the visportal is within a door (see next section.) For the visportal to be effective it does not matter if the rest of the visportal brush sticks out into space so long as the edges of the visportal-textured face are surrounded by solid brush. In practice you will probably put most fully within a corridor or doorway, a city street (yes, the sky above is solid), etc. Irregular shaped gaps must still be plugged with a rectangular visportal which should then overlap into the solid and leave no gaps. This will also make sound propagation work correctly.

Generally you will place visportals on bends in the terrain around which the player cannot see from the current viewpoint. Avoid placing visportals in a line along a corridor or street for example. Since the player can see straight down through them all then they serve no purpose as they will all be open and visportals themselves create extra triangles and complexity (see downside section below.)

Try to find the smallest gaps where possible to place visportals. The smaller the visportal then the smaller the view aperture and so the less chance of lining up those apertures. Remember, visportals beyond the first one remain closed until they intersect a nearer open visportal in the player's view. Even without a door, an open doorway is a better place for a visportal than a wider corridor or room beyond. Imagine trying to get a straight pole through as many of these visportal rectangles as possible; the narrower and less aligned they are then the harder to get the pole very far.

Don't get too hung up on perfect placement of every last visportal. Generally if you follow this guide and use your judgement you achieve a satisfactory game performance. Examine some large maps that you know work well to get some ideas where visportals are placed using the r_showPortals 1 command.

What if you put visportal texture on both main faces of the visportal brush? Only one will be effective. If the visportal brush juts out into space then visportal texture at that end will not work but the one at the other end will be the operative one. If you rotated the brush then it still works and uses whichever one is surrounded by solid. If both are in space it does not work at all. If both are surrounded by solid then only one works. Which one? Hard to tell. It seems to be determined by the local geometry. It is interesting to note that when you use r_showTris 3 to see what is rendered then the triangles are confined to either side of the visportal face. In other words, a long corridor wall rendered as two large triangles would now be split into four triangles. So a visportal might be considered to help with multiple lighting performance as you do not need to visually change the terrain with trim etc.

What if you put visportal texture on all the surfaces of the brush? Only one is effective (must be surrounded by solid brush.) To be certain of optimum performance use nodraw on all surfaces except the one face with visportal texture.

Visportals and doors

A visportal in contact with a door that has an openable property is automatically closed when the door is closed and automatically becomes conventionally operative when the door opens. By 'operative' I mean it is then like a normal visportal and will be open or closed depending on the player's view. So when you first go through a door and leave it open then its visportal will be open as you look immediately back at it. But as you then proceed further through other visportals, the door visportal will eventually close (prevent rendering through it) even if the door itself is left open.

Doors standing in front of but not within a doorway

Note that the visportal only needs to be in contact with the door to be affected by it. Normally you would place the visportal within the door but it actually only needs its visportal-textured surface to touch it. This means that if you have a door that is stood in front of an opening in a wall then you cannot put the visportal inside the door because it will not be surrounded by solid brush. But you can put a visportal just inside the opening and flush with the mouth of the opening and the door immediately in front of that and in contact with the visportal. You can test this by placing the door offset well to one side but part of it still in contact with the visportal. In game you can see the opening as the door is only partially covering it. When the door is closed the visportal closes and stops rendering through the doorway. You will see this as a black panel in the doorway. As the door opens the black panel disappears and you can see through the doorway again. You might think that from the other side the black panel would obscure the door when closed but it doesn't. With the door centred in its normal position, typically you might have an entity frame around the door. If you had a solid brush frame without gaps then the visportal could be inside the door if you wanted as it would then have solid all round its edges. In many cases of course, the door frame, whether entity or brush, would be within the solid brush doorway anyway.

Windows, Doors with windows, bars, etc.

Openable doors that let you see through them such as windows, doors with windows, barred gates, etc. should not be in contact with a visportal. When the door is closed it will automatically close any visportal whose effective surface is in touch with it. The visportal will not then permit any rendering through it and will show as a black panel in the window or between the bars of a gate. Instead, move the visportal further along away from the door. It will still function effectively as a normal visportal just as if the door were not there. This does not of course apply to simulated windows such as a glazed textured panel on a door texture where you cannot actually see through.

All doors and windows that do not have an openable property can have a visportal in touch with them as it will not be affected by them and it will just function as a normal visportal.

Need I design, even compromise my map to make best use of visportals?

You need to design your map from the start as a series of connected boxes (brushes) with the player's view and visportals in mind. And yes, sometimes you might need to add a bend you don't want or obstruct a view in some way so you can put in another visportal if you are having or expecting slow down in a large and/or complex area. This is a matter of experience. If you have large complex areas and are experiencing frame lag but can see no obvious place to put a visportal then you might need to compromise your terrain and add some solid brush barriers to block certain views with visportals in the access round or through them.

Note that it is not essential that visportals be only at the actual joins between brushes; they still work even if they are half way down a corridor so long as they are wedged in tight without gaps. But you will mostly place them at joins.

For rendering considerations, the player's view is everything and every room and street in front of you even if there are walls, etc. in the way. Imagine what you would see with X-Ray vision. What is behind you or just out of range of the screen does not matter. But visportals restrict the view to what can be seen through the rectangle of the visportal.

It is not necessary to put visportals at every tiny bend in the map; in fact that should be avoided in smaller areas because visportals themselves create extra triangles and complexity (see downside section below.) Try to keep in mind what will be rendered through the visportals and judge what would not cause frame lag slowdown if the player could actually see that view. Three or four bends without visportals in a restricted air duct is not going to cause any problem if the duct is correctly visportalled at the ends for example.

Is there a downside?

One downside to visportals is that is extra work for the mapper! Another is that they split the geometry and create extra triangles and batches. This will not normally cause a problem unless your map has a very large number of areas. The advantages in performance of using visportals far outweigh the downsides!

See also

There are other good visportal tutorials to be found under: http://www.iddevnet.com/doom3/visportals.php and http://www.modwiki.net/wiki/Visportal

In addition, Sound propagation relies on visportals. For details study Sound Propagation: Part 1 and Sound Propagation: Part 2