Visportals

written by Fidcal

What are visportals?

Visportals are brushes between areas of a doom map, seperating the map into smaller parts and are 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 are also very important for sound propagation. Without them, sounds can travel through brushwork and reach areas of the map that they shouldn't.

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 processed visportals as wireframe in-game for testing - even right through walls they are visible. A green wireframe is an 'open' visportal and renders everything beyond it up to the next visportal. A red wireframe is a 'closed' visportal with nothing rendered beyond it and no further visportals beyond that are even processed so are not visible at all. If a visportal does not show then it is either beyond range of processing or it is not working so check it is set up correctly.

What is rendering?

Rendering might be regarded as the calculating of surface lighting, colour, texture, etc. Not all rendered surfaces are visible in-game but still have to be calculated. Others do not need rendering at all. Processing only takes place in the current portal area, that is, up to the nearest closed visportals. Surfaces are treated as divided into triangles for rendering purposes. The r_showTris console command shows those triangles as wireframes. In the console use r_showTris N where N is...

• 0 - Off - normal gameplay with no wireframes shown.
• 1 - Shows only triangles that are visible in-game (not hidden behind other surfaces.) These visible surfaces are only part of what is rendered.
• 2 - Shows as wireframes, all triangle surfaces that would be rendered in-game. This includes those hidden behind other surfaces BUT ONLY IF they face the player, even slightly. Surfaces facing away from the player are never rendered.
• 3 - Shows as wireframes, all triangle surfaces even if not rendered.

You can see that for the purpose of testing performance use 2 above which shows all that would be rendered (whether visible to the player or not.) You can use 3 to see all triangles up to the next closed visportal but remember not all of it will be rendered so will not affect performance.

You might also use r_useScissor 0 to show geometry outside the visportal wireframe 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. Only be concerned with that one surface as the rest of the brush merely carries it. So to create one you just....

• Make a thin brush like a wall. Ideally make it rectangular for best sound propagation (see Sound Propagation later.) It can extend beyond the gap so does not necessarily need to be the same shape - see Where to place your Visportal later.
• 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 + 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. Always think of visportals as one flat face and the rest of the brush can be ignored for functional purposes.

Where to place your Visportal

It will eventually be wedged tight like a plug into gaps, doorways, etc. between areas. The edges of the visportal-textured face of visportals should be completely sealed by or in solid worldspawn brush that has no gaps. The brush must be a child of worldspawn and not an entity. 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 worldspawn brush and/or another visportal brush (see later) In practice you will probably put most fully within a corridor or doorway, a city street (yes, the sky above is solid worldspawn brush), etc. Irregular shaped gaps must still be plugged with a rectangular visportal which should then overlap into the solid worldspawn and leave no gaps. This will also make sound propagation work correctly (see Sound Propagation later.)

Each area you thus created must be totally enclosed with worldspawn brushes with no gaps of either space else an entity. So a closed building with visportals at the doors but a tiny gap under the eaves of the roof won't work! Also avoid only blocking gaps with entities whether brushes or models. For example, a two-sided window entity that completely fills the opening will not seal the area for portalling purposes. Do not put in a visportal unless the window is either transparent or can be opened (like a door.) Instead put in a worldspawn brush with nodraw texture on it so it will not be visible or collidable just in front of the window. Or if you are using two windows back to back (say a lit one outside and an unlit one inside then a thin caulk brush between them.

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.)

With a large building surrounded by a walled open area then try visportals at each corner. If it is a very large building then also add visportals midway along each side. The player standing at one corner might be able to see up two sides, part of a far side, and even a small part of the fourth side so all sides would be rendered. By having extra visportals middway along each side then at least half of each side of the furthest corner need not be rendered (consider also preventing the player reaching such a viewpoint with an obstruction!)

Subject to the above, 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 do not open unless they intersect all open visportals in that line of 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 apertures 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.

Multiple Joined Visportals

Because visportals are a single face, by their very nature they can only be placed on a single brush. But visportal brushes can be placed or merged together to fill more complex shaped gaps. For example, a wide rectangle might have one side clipped to slope over a roof while the rectangular part of its shape sits on top of another rectangle across the street below. But complexity affects performance so only do this if one rectangular visportal intruding into interior walls might do the same job. Remember, it does not matter if the visportal overlaps into solid so if there is an interior wall on the same plane (or indeed if the building is totally solid) then the visportal can penetrate it and still function. Do not use multiple visportals just to shape nicely around solid building trim and structure but intrude into it so long as the edge does not exit into space at any point it will be fine.

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.

Visportal switches: func_portals

The preceding section Visportals and doors makes clear that doors can function like switches to enable and close visportals in contact with them. func_portals can be directly triggered to do the same. You just place the func_portal so that it intersects with a visportal. Triggering the func_portal will close/enable the visportal. As with doors, even if enabled the visportal will still not be open if it is not in the player's view.

To set up a trigger:

WIP

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 aperture 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!

Sound Propagation

Correct propagation of sound from the player to AI relies on visportals. That is, AI will hear the player through the pathways of visportals. This is designed around rectangular visportals so ideally always use rectangular visportals unless you have no choice with an awkwardly shaped gap or if the gap is out of range of AI, for example along a sloping roof where AI never go. To reduce complexity, sound is passed through the centre of visportals without four sides. This will be okay for smaller visportals, but the error (path difference from the minimal path) will get more noticeable the larger the visportal. It also still assumes that when you do have four sides, they are perpendicular. If you have some non-90 degree angles between the sides, some weirdness may ensue. So an AI that is alerted in the dark (or facing away) by hearing the player on the same side of the road might run to the centre of a road and back rather than direct to where the player made the noise. Irregular visportals at AI level that large to make this effect noticeable are likely to be uncommon.

Visportals function individually even if joined together into complex shapes. So a rectangle at ground level topped by an angled visportal above it tilting out over a roof will be treated separately not as one aperture.

The bottom line is, with any non-rectangular visportals keep the above in mind and if in doubt then consider early testing of AI's alert to player sound.

Sound to the player from any source are blocked by closed visportals but once opened then the sound passes directly from source to the player in a straight line even through solid brushes.

For details study: Sound Propagation: Part 1 and Sound Propagation: Part 2

Trouble-shooting

There are two possible problems I can think of: the visportal doesn't work at all or it works yet there is too much being rendered giving poor performance and frame lag. The latter problem is a matter of experience and experimentation. Often much ingenuity is needed to place visportals to reduce the size of areas being rendered at any one time. There is probably a different solution for every situation. Ultimately you might be forced to change the terrain to help visportalling.

If a visportal doesn't work at all (eg, does not show as either red or green while you are directly in its area and looking at it and you have r_showPortals enabled) then you can try the following.

• Check which face of the visportal is facing which way. It sometimes happen one clones a visportal and rotates it the wrong way without realizing. So the wrong face is in the right place but the visportal face is not in contact with worldspawn.

• Make sure the visportal hasn't been assigned to an entity but is worldspawn.

• Search for gaps anywhere around the edges of the visportal face. Check for grid snapping not only of the visportal but the surrounding brushes. A tiny difference might not be visible in the Dark Radiant grid if you are not zoomed in sufficiently.

• Check all surrounding items to see if any are entities. Remember, the visportal face must only be surrounded by worldspawn brushes. It seems to be mostly OK if the visportal cuts through an entity so long as it meets worldspawn at its edges.

• If all else fails then do the following:
• Clone the visportal and drag one edge to one side, that is, reduce its size to say half.
• Select the original and drag its opposite edge the other way so you now have two visportals pressed together and which together fill the gap. Guess which side unless you suspect one side particularly (see later.)
• Change one of the visportals to any normal visible simple texture, stone, wood, whatever so that now the original gap is smaller and filled by just one smaller visportal. (with hindsight, I think this would probably work anyway and might even be better just leaving it as visportal so you can see which one works but I'll continue with what I did!)
• Check it in game.
• If it still does not work then reduce it further, perhaps by half as much again. In particular, go past edges of surrounding brushes (eg, if working downwards with two brushes on the left then maybe it's the top brush that is the problem so reduce the top of the visportal below its bottom edge.) Obviously as you reduce the visportal you increase the solid temporary brush you made equally to keep up so there is never a gap.
• If the visportal still does not work even when reduced to a slither then try the same for all four sides noting that the three sides against the slither of visportal are obviously first suspects.
• If eventually the visportal starts to work then you know the error is in the other section where you have the solid temporary brush. Use a process of elimination to track down exactly where the error is.
• You might even have to create a third temporary brush or even a fourth but you must eventually force the visportal to work even if you surround it with four new brushes! Once working, then reduce, remove, gradually until the error re-appears - that must be where the error lies. So by a process of elimination you should track down the source of the problem.
• The result might make not seem to make sense but at least if you locate the error you can try things to solve the problem. I had a visportal up to the sky and on its left against the top of a triangle of bricks on which rested a roof. The visportal seemed to be perfectly surrounded by worldspawn but I reduced it slightly with just a slim temporary solid test brush only one unit high above it pressing against the top of this triangle. The visportal was now working yet if I removed that slim test brush and raised the visportal to the top again then it would not work. Made no sense to me unless mathematically the very top pixel of the triangle might be regarded as infinitely thin and therefore a gap. So, I left the thin test brush and gave it sky texture so it's completely invisible and everything works.

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