direct.showbase.ShowBase

from direct.showbase.ShowBase import ShowBase, WindowControls, exitfunc

This module contains ShowBase, an application framework responsible for opening a graphical display, setting up input devices and creating the scene graph.

The simplest way to open a ShowBase instance is to execute this code:

from direct.showbase.ShowBase import ShowBase

base = ShowBase()
base.run()

A common approach is to create your own subclass inheriting from ShowBase.

Built-in global variables

Some key variables used in all Panda3D scripts are actually attributes of the ShowBase instance. When creating an instance of this class, it will write many of these variables to the built-in scope of the Python interpreter, so that they are accessible to any Python module, without the need for extra imports. For example, the ShowBase instance itself is accessible anywhere through the base variable.

While these are handy for prototyping, we do not recommend using them in bigger projects, as it can make the code confusing to read to other Python developers, to whom it may not be obvious where these variables are originating.

Refer to the builtins page for a listing of the variables written to the built-in scope.

Inheritance diagram

class ShowBase(fStartDirect=True, windowType=None)

Bases: DirectObject

SetAllSfxEnables(self, bEnabled)

Calls setActive(bEnabled) on all valid SFX managers.

__init__(self, fStartDirect=True, windowType=None)

Opens a window, sets up a 3-D and several 2-D scene graphs, and everything else needed to render the scene graph to the window.

To prevent a window from being opened, set windowType to the string ‘none’ (or ‘offscreen’ to create an offscreen buffer). If this is not specified, the default value is taken from the ‘window-type’ configuration variable.

This constructor will add various things to the Python builtins scope, including this instance itself (under the name base).

addAngularIntegrator(self)

Adds a AngularEulerIntegrator to the default physics manager. By default, only a LinearEulerIntegrator is attached.

addSfxManager(self, extraSfxManager)

Adds an additional SFX audio manager to sfxManagerList, the list of managers managed by ShowBase.

adjustWindowAspectRatio(self, aspectRatio)

This function is normally called internally by windowEvent(), but it may also be called to explicitly adjust the aspect ratio of the render/render2d DisplayRegion, by a class that has redefined these.

appRunner

This contains the global appRunner instance, as imported from AppRunnerGlobal. This will be None if we are not running in the runtime environment (ie. from a .p3d file). Deprecated.

attachInputDevice(self, device, prefix=None, watch=False)

This function attaches an input device to the data graph, which will cause the device to be polled and generate events. If a prefix is given and not None, it is used to prefix events generated by this device, separated by a hyphen.

The watch argument can be set to True (as of Panda3D 1.10.3) to set up the default MouseWatcher to receive inputs from this device, allowing it to be polled via mouseWatcherNode and control user interfaces. Setting this to True will also make it generate unprefixed events, regardless of the specified prefix.

If you call this, you should consider calling detachInputDevice when you are done with the device or when it is disconnected.

backfaceCullingOff(self)

Enables two-sided rendering on the entire 3D scene graph.

backfaceCullingOn(self)

Disables two-sided rendering on the entire 3D scene graph.

bboard

The global bulletin board, as imported from BulletinBoardGlobal.

bufferViewer

Utility for viewing offscreen buffers, see BufferViewer.

cTrav

A placeholder for a CollisionTraverser. If someone stores a CollisionTraverser pointer here, ShowBase will traverse it automatically in the collisionLoop task, so you won’t need to call traverse() yourself every frame.

cam

This is a NodePath pointing to the Camera object set up for the 3D scene. Usually a child of camera.

cam2d

Same as cam, but for the 2D scene graph.

cam2dp

Same as cam2d, but for the 2D overlay scene graph.

camLens

Convenience accessor for base.camNode.get_lens(), containing a Lens object.

camList

A list of all cameras created with makeCamera(), including cam.

camNode

Convenience accessor for base.cam.node(), containing a Camera object.

camera

This is the NodePath that should be used to manipulate the camera. It points at the node to which the default camera (cam, camNode) is attached.

camera2d

Same as camera, but for the 2D scene graph. Parent of cam2d.

camera2dp

Same as camera2d, but for the 2D overlay scene graph. Parent of cam2dp.

changeMouseInterface(self, changeTo)

Change the mouse interface used to control the camera.

clock

This is the global ClockObject.

closeWindow(self, win, keepCamera=False, removeWindow=True)

Closes the indicated window and removes it from the list of windows. If it is the main window, clears the main window pointer to None.

config = <module 'direct.showbase.DConfig' from '/opt/hostedtoolcache/Python/3.7.17/x64/lib/python3.7/site-packages/direct/showbase/DConfig.py'>

The deprecated DConfig interface for accessing config variables.

createBaseAudioManagers(self)

Creates the default SFX and music manager. Called automatically from the ShowBase constructor.

createStats(self, hostname=None, port=None)

If want-pstats is set in Config.prc, or the wantStats member is otherwise set to True, connects to the PStats server. This is normally called automatically from the ShowBase constructor.

destroy(self)

Call this function to destroy the ShowBase and stop all its tasks, freeing all of the Panda resources. Normally, you should not need to call it explicitly, as it is bound to the exitfunc and will be called at application exit time automatically.

This function is designed to be safe to call multiple times.

detachInputDevice(self, device)

This should be called after attaching an input device using attachInputDevice and the device is disconnected or you no longer wish to keep polling this device for events.

You do not strictly need to call this if you expect the device to be reconnected (but be careful that you don’t reattach it).

devices

This is the global InputDeviceManager, which keeps track of connected input devices.

disableAllAudio(self)

Disables all SFX and music managers, meant to be called when the app loses audio focus.

disableMouse(self)

Temporarily disable the mouse control of the camera, either via the drive interface or the trackball, whichever is currently in use.

disableParticles(self)

The opposite of enableParticles().

enableAllAudio(self)

Reenables the SFX and music managers that were active at the time disableAllAudio() was called. Meant to be called when the app regains audio focus.

enableMouse(self)

Reverse the effect of a previous call to disableMouse(). useDrive() also implicitly enables the mouse.

enableMusic(self, bEnableMusic)

Enables or disables the music manager.

enableParticles(self)

Enables the particle and physics managers, which are stored in particleMgr and physicsMgr members, respectively. Also starts a task to periodically update these managers.

By default, only a LinearEulerIntegrator is attached to the physics manager. To attach an angular integrator, follow this up with a call to addAngularIntegrator().

enableSoftwareMousePointer(self)

Creates some geometry and parents it to render2d to show the currently-known mouse position. Useful if the mouse pointer is invisible for some reason.

enableSoundEffects(self, bEnableSoundEffects)

Enables or disables SFX managers.

eventMgr

The global event manager, as imported from EventManagerGlobal.

exitFunc

Fill this in with a function to invoke when the user “exits” the program by closing the main window.

finalExitCallbacks

Add final-exit callbacks to this list. These will be called when sys.exit() is called, after Panda has unloaded, and just before Python is about to shut down.

finalizeExit(self)

Called by userExit() to quit the application. The default implementation just calls sys.exit().

getAlt(self)

Returns True if the alt key is currently held down.

getAspectRatio(self, win=None)

getAxes(self)

Loads and returns the models/misc/xyzAxis.bam model.

Return type

panda3d.core.NodePath

getBackgroundColor(self, win=None)

Returns the current window background color. This assumes the window is set up to clear the color each frame (this is the normal setting).

Return type

panda3d.core.VBase4

getControl(self)

Returns True if the control key is currently held down.

getExitErrorCode(self)

getMeta(self)

Returns True if the meta key is currently held down.

getRepository(self)

getShift(self)

Returns True if the shift key is currently held down.

getSize(self, win=None)

Returns the actual size of the indicated (or main window), or the default size if there is not yet a main window.

graphicsEngine

The global GraphicsEngine, as returned by GraphicsEngine.getGlobalPtr()

initShadowTrav(self)

isParticleMgrEnabled(self)

Returns True if enableParticles() has been called.

isPhysicsMgrEnabled(self)

Returns True if enableParticles() has been called.

jobMgr

The global job manager, as imported from JobManagerGlobal.

loadMusic(self, name)

Deprecated

Use Loader.Loader.loadMusic() instead.

loadSfx(self, name)

Deprecated

Use Loader.Loader.loadSfx() instead.

loader

Loader.Loader object.

mainDir

The directory containing the main Python file of this application.

makeAllPipes(self)

Creates all GraphicsPipes that the system knows about and fill up pipeList with them.

makeCamera(self, win, sort=0, scene=None, displayRegion=(0, 1, 0, 1), stereo=None, aspectRatio=None, clearDepth=0, clearColor=None, lens=None, camName='cam', mask=None, useCamera=None)

Makes a new 3-d camera associated with the indicated window, and creates a display region in the indicated subrectangle.

If stereo is True, then a stereo camera is created, with a pair of DisplayRegions. If stereo is False, then a standard camera is created. If stereo is None or omitted, a stereo camera is created if the window says it can render in stereo.

If useCamera is not None, it is a NodePath to be used as the camera to apply to the window, rather than creating a new camera.

Return type

panda3d.core.NodePath

makeCamera2d(self, win, sort=10, displayRegion=(0, 1, 0, 1), coords=(-1, 1, -1, 1), lens=None, cameraName=None)

Makes a new camera2d associated with the indicated window, and assigns it to render the indicated subrectangle of render2d.

Return type

panda3d.core.NodePath

makeCamera2dp(self, win, sort=20, displayRegion=(0, 1, 0, 1), coords=(-1, 1, -1, 1), lens=None, cameraName=None)

Makes a new camera2dp associated with the indicated window, and assigns it to render the indicated subrectangle of render2dp.

Return type

panda3d.core.NodePath

makeDefaultPipe(self, printPipeTypes=None)

Creates the default GraphicsPipe, which will be used to make windows unless otherwise specified.

makeModulePipe(self, moduleName)

Returns a GraphicsPipe from the indicated module, e.g. ‘pandagl’ or ‘pandadx9’. Does not affect base.pipe or base.pipeList.

Return type

panda3d.core.GraphicsPipe

messenger

The global messenger, as imported from MessengerGlobal.

mouseWatcherNode

The MouseWatcher object, created by setupMouse().

movie(self, namePrefix='movie', duration=1.0, fps=30, format='png', sd=4, source=None)

Spawn a task to capture a movie using the screenshot function.

Parameters

• namePrefix (str) – used to form output file names (can include path information (e.g. ‘/i/beta/frames/myMovie’)

• duration (float) – the length of the movie in seconds

• fps (float) – the frame rate of the resulting movie

• format (str) – specifies output file format (e.g. png, bmp)

• sd (int) – specifies number of significant digits for frame count in the output file name (e.g. if sd = 4, the name will be something like movie_0001.png)

• source – the Window, Buffer, DisplayRegion, or Texture from which to save the resulting images. The default is the main window.

Returns

A Task that can be awaited.

notify = <direct.directnotify.Notifier.Notifier object>

oobe(self, cam=None)

Enable a special “out-of-body experience” mouse-interface mode. This can be used when a “god” camera is needed; it moves the camera node out from under its normal node and sets the world up in trackball state. Button events are still sent to the normal mouse action node (e.g. the DriveInterface), and mouse events, if needed, may be sent to the normal node by holding down the Control key.

This is different than useTrackball(), which simply changes the existing mouse action to a trackball interface. In fact, OOBE mode doesn’t care whether useDrive() or useTrackball() is in effect; it just temporarily layers a new trackball interface on top of whatever the basic interface is. You can even switch between useDrive() and useTrackball() while OOBE mode is in effect.

This is a toggle; the second time this function is called, it disables the mode.

oobeCull(self, cam=None)

While in OOBE mode (see above), cull the viewing frustum as if it were still attached to our original camera. This allows us to visualize the effectiveness of our bounding volumes.

openDefaultWindow(self, *args, **kw)

Creates the main window for the first time, without being too particular about the kind of graphics API that is chosen. The suggested window type from the load-display config variable is tried first; if that fails, the first window type that can be successfully opened at all is accepted.

This is intended to be called only once, at application startup. It is normally called automatically unless window-type is configured to ‘none’.

Returns

True on success, False on failure.

openMainWindow(self, *args, **kw)

Creates the initial, main window for the application, and sets up the mouse and render2d structures appropriately for it. If this method is called a second time, it will close the previous main window and open a new one, preserving the lens properties in base.camLens.

Returns

True on success, or False on failure (in which case base.win may be either None, or the previous, closed window).

openWindow(self, props=None, fbprops=None, pipe=None, gsg=None, host=None, type=None, name=None, size=None, aspectRatio=None, makeCamera=True, keepCamera=False, scene=None, stereo=None, unexposedDraw=None, callbackWindowDict=None, requireWindow=None)

Creates a window and adds it to the list of windows that are to be updated every frame.

Parameters

• props – the WindowProperties that describes the window.

• fbprops – the FrameBufferProperties indicating the requested framebuffer properties.

• type – Either ‘onscreen’, ‘offscreen’, or ‘none’.

• keepCamera – If True, the existing base.cam is set up to render into the new window.

• makeCamera – If True (and keepCamera is False), a new camera is set up to render into the new window.

• unexposedDraw – If not None, it specifies the initial value of setUnexposedDraw().

• callbackWindowDict – If not None, a CallbackGraphicsWindow is created instead, which allows the caller to create the actual window with its own OpenGL context, and direct Panda’s rendering into that window.

• requireWindow – If True, the function should raise an exception if the window fails to open correctly.

Return type

panda3d.core.GraphicsWindow

particleMgr

If enableParticles() has been called, this is the particle manager as imported from direct.particles.ParticleManagerGlobal.

physicsMgr

If enableParticles() has been called, this is the physics manager as imported from direct.showbase.PhysicsManagerGlobal.

pipe

Contains the GraphicsPipe object created by makeDefaultPipe().

pipeList

The full list of GraphicsPipe objects, including any auxiliary pipes. Filled by makeAllPipes().

playMusic(self, music, looping=0, interrupt=1, volume=None, time=0.0)

playSfx(self, sfx, looping=0, interrupt=1, volume=None, time=0.0, node=None, listener=None, cutoff=None)

popCTrav(self)

printEnvDebugInfo(self)

Print some information about the environment that we are running in. Stuff like the model paths and other paths. Feel free to add stuff to this.

pushCTrav(self, cTrav)

removeCameraFrustum(self)

restart(self, clusterSync=False, cluster=None)

reviveInput(self)

Restores inputs after a previous call to silenceInput().

run(self)

This method runs the TaskManager when self.appRunner is None, which is to say, when we are not running from within a p3d file. When we are within a p3d file, the Panda3D runtime has to be responsible for running the main loop, so we can’t allow the application to do it.

saveCubeMap(self, namePrefix='cube_map_#.png', defaultFilename=0, source=None, camera=None, size=128, cameraMask= 0111 1111 1111 1111 1111 1111 1111 1111, sourceLens=None)

Similar to screenshot(), this sets up a temporary cube map Texture which it uses to take a series of six snapshots of the current scene, one in each of the six cube map directions. This requires rendering a new frame.

Unlike screenshot(), source may only be a GraphicsWindow, GraphicsBuffer, or DisplayRegion; it may not be a Texture.

camera should be the node to which the cubemap cameras will be parented. The default is the camera associated with source, if source is a DisplayRegion, or base.camera otherwise.

Returns

The filename if successful, or None if there is a problem.

saveSphereMap(self, namePrefix='spheremap.png', defaultFilename=0, source=None, camera=None, size=256, cameraMask= 0111 1111 1111 1111 1111 1111 1111 1111, numVertices=1000, sourceLens=None)

This works much like saveCubeMap(), and uses the graphics API’s hardware cube-mapping ability to get a 360-degree view of the world. But then it converts the six cube map faces into a single fisheye texture, suitable for applying as a static environment map (sphere map).

For eye-relative static environment maps, sphere maps are often preferable to cube maps because they require only a single texture and because they are supported on a broader range of hardware.

Returns

The filename if successful, or None if there is a problem.

screenshot(self, namePrefix='screenshot', defaultFilename=1, source=None, imageComment='')

Captures a screenshot from the main window or from the specified window or Texture and writes it to a filename in the current directory (or to a specified directory).

If defaultFilename is True, the filename is synthesized by appending namePrefix to a default filename suffix (including the filename extension) specified in the Config variable screenshot-filename. Otherwise, if defaultFilename is False, the entire namePrefix is taken to be the filename to write, and this string should include a suitable filename extension that will be used to determine the type of image file to write.

Normally, the source is a GraphicsWindow, GraphicsBuffer or DisplayRegion. If a Texture is supplied instead, it must have a ram image (that is, if it was generated by makeTextureBuffer() or makeCubeMap(), the parameter toRam should have been set true). If it is a cube map texture as generated by makeCubeMap(), namePrefix should contain the hash mark (‘#’) character.

Returns

The filename if successful, or None if there is a problem.

setAspectRatio(self, aspectRatio)

Sets the global aspect ratio of the main window. Set it to None to restore automatic scaling.

setBackgroundColor(self, r=None, g=None, b=None, a=0.0, win=None)

Sets the window background color to the indicated value. This assumes the window is set up to clear the color each frame (this is the normal setting).

The color may be either a VBase3 or a VBase4, or a 3-component tuple, or the individual r, g, b parameters.

setFrameRateMeter(self, flag)

Turns on or off (according to flag) a standard frame rate meter in the upper-right corner of the main window.

setMouseOnNode(self, newNode)

setSceneGraphAnalyzerMeter(self, flag)

Turns on or off (according to flag) a standard frame rate meter in the upper-right corner of the main window.

setSleep(self, amount)

Sets up a task that calls python ‘sleep’ every frame. This is a simple way to reduce the CPU usage (and frame rate) of a panda program.

setupDataGraph(self)

Creates the data graph and populates it with the basic input devices.

setupMouse(self, win, fMultiWin=False)

Creates the structures necessary to monitor the mouse input, using the indicated window. If the mouse has already been set up for a different window, those structures are deleted first.

Parameters

fMultiWin – If True, then the previous mouse structures are not deleted; instead, multiple windows are allowed to monitor the mouse input. However, in this case, the trackball controls are not set up, and must be set up by hand if desired.

Returns

The ButtonThrower NodePath created for this window.

setupMouseCB(self, win)

setupRender(self)

Creates the render scene graph, the primary scene graph for rendering 3-d geometry.

setupRender2d(self)

Creates the render2d scene graph, the primary scene graph for 2-d objects and gui elements that are superimposed over the 3-d geometry in the window.

setupRender2dp(self)

Creates a render2d scene graph, the secondary scene graph for 2-d objects and gui elements that are superimposed over the 2-d and 3-d geometry in the window.

setupWindowControls(self, winCtrl=None)

showCameraFrustum(self)

shutdown(self)

silenceInput(self)

This is a heavy-handed way of temporarily turning off all inputs. Bring them back with reviveInput().

spawnTkLoop(self)

Call this method to hand the main loop over to Tkinter. This sets up a timer callback so that Panda still gets updated, but Tkinter owns the main loop (which seems to make it happier than the other way around).

spawnWxLoop(self)

Call this method to hand the main loop over to wxPython. This sets up a wxTimer callback so that Panda still gets updated, but wxPython owns the main loop (which seems to make it happier than the other way around).

startDirect(self, fWantDirect=1, fWantTk=1, fWantWx=0)

startTk(self, fWantTk=True)

startWx(self, fWantWx=True)

taskMgr

The global task manager, as imported from TaskManagerGlobal.

textureOff(self)

Disables texturing on the entire 3D scene graph.

textureOn(self)

Undoes the effects of a previous call to textureOff().

tkRun(self)

This method replaces run() after we have called spawnTkLoop(). Since at this point Tkinter now owns the main loop, this method is a call to tkRoot.mainloop().

toggleBackface(self)

Toggles between backfaceCullingOn() and backfaceCullingOff().

toggleParticles(self)

Calls enableParticles() or disableParticles() depending on the current state.

toggleShowVertices(self)

Toggles a mode that visualizes vertex density per screen area.

toggleTexMem(self)

Toggles a handy texture memory watcher utility. See direct.showutil.TexMemWatcher for more information.

toggleTexture(self)

Toggles between textureOn() and textureOff().

toggleWireframe(self)

Toggles between wireframeOn() and wireframeOff().

transitions

Transitions.Transitions object.

updateManagers(self, state)

useDrive(self)

Changes the mouse interface used for camera control to drive mode.

useTrackball(self)

Changes the mouse interface used for camera control to trackball mode.

userExit(self)

win

This is the main, or only window; see winList for a list of all windows.

winList

A list of all windows opened via openWindow().

windowEvent(self, win)

windowType

This is set to the value of the window-type config variable, but may optionally be overridden in the Showbase constructor. Should either be ‘onscreen’ (the default), ‘offscreen’ or ‘none’.

wireframeOff(self)

Undoes the effects of a previous call to wireframeOn().

wireframeOn(self)

Enables wireframe rendering on the entire 3D scene graph.

wxApp

This is used to store the wx.Application object used when want-wx is set or startWx() is called.

wxRun(self)

This method replaces run() after we have called spawnWxLoop(). Since at this point wxPython now owns the main loop, this method is a call to wxApp.MainLoop().

class WindowControls(win, cam=None, camNode=None, cam2d=None, mouseWatcher=None, mouseKeyboard=None, closeCmd=<function WindowControls.<lambda>>, grid=None)

Bases: object

__init__(self, win, cam=None, camNode=None, cam2d=None, mouseWatcher=None, mouseKeyboard=None, closeCmd=<function WindowControls.<lambda>>, grid=None)

exitfunc()