DisplayRegion¶
from panda3d.core import DisplayRegion
-
class
DisplayRegion
¶ Bases:
TypedReferenceCount
,DrawableRegion
A rectangular subregion within a window for rendering into. Typically, there is one DisplayRegion that covers the whole window, but you may also create smaller DisplayRegions for having different regions within the window that represent different scenes. You may also stack up DisplayRegions like panes of glass, usually for layering 2-d interfaces on top of a 3-d scene.
Inheritance diagram
-
property
active
→ bool¶ - Getter
Returns the active flag associated with the
DisplayRegion
.- Setter
Sets the active flag associated with the
DisplayRegion
. If theDisplayRegion
is marked inactive, nothing is rendered.Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.
-
property
camera
→ NodePath¶ - Getter
Returns the camera associated with this
DisplayRegion
, or an emptyNodePath
if no camera is associated.- Setter
Sets the camera that is associated with this
DisplayRegion
. There is a one-to-many association between cameras andDisplayRegions
; one camera may be shared by multipleDisplayRegions
.The camera is actually set via a
NodePath
, which clarifies which instance of the camera (if there happen to be multiple instances) we should use.Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.
-
clearCullCallback
() → None¶ Removes the callback set by an earlier call to
setCullCallback()
.
-
clearDrawCallback
() → None¶ Removes the callback set by an earlier call to
setDrawCallback()
.
-
property
cull_callback
→ CallbackObject¶ - Getter
Returns the
CallbackObject
set bysetCullCallback()
.- Setter
Sets the
CallbackObject
that will be notified when theDisplayRegion
is visited during the cull traversal. This callback will be made during the cull thread.The cull traversal is responsible for determining which nodes are visible and within the view frustum, and for accumulating state and transform, and generally building up the list of CullableObjects that are to be eventually passed to the draw traversal for rendering.
At the time the cull traversal callback is made, the traversal for this
DisplayRegion
has not yet started.The callback is passed an instance of a
DisplayRegionCullCallbackData
, which contains pointers to the current scene information, as well as the currentDisplayRegion
and GSG. The callback replaces the normal cull behavior, so if your callback does nothing, the scene graph will not be traversed and therefore nothing will be drawn. If you wish the normal cull traversal to be performed for thisDisplayRegion
, you must call cbdata->upcall() from your callback.
-
property
cull_traverser
→ CullTraverser¶ - Getter
Returns the
CullTraverser
that will be used to draw the contents of thisDisplayRegion
.- Setter
Specifies the
CullTraverser
that will be used to draw the contents of thisDisplayRegion
. Normally the defaultCullTraverser
is sufficient, but this may be changed to change the default cull behavior.
-
property
dimensions
→ LVecBase4¶ - Getter
Retrieves the coordinates of the DisplayRegion’s rectangle within its
GraphicsOutput
. These numbers will be in the range [0..1].Retrieves the coordinates of the DisplayRegion’s rectangle within its
GraphicsOutput
. These numbers will be in the range [0..1].Retrieves the coordinates of the DisplayRegion’s rectangle within its
GraphicsOutput
. These numbers will be in the range [0..1].- Setter
Changes the portion of the framebuffer this
DisplayRegion
corresponds to. The parameters range from 0 to 1, where 0,0 is the lower left corner and 1,1 is the upper right; (0, 1, 0, 1) represents the whole screen.Changes the portion of the framebuffer this
DisplayRegion
corresponds to. The parameters range from 0 to 1, where 0,0 is the lower left corner and 1,1 is the upper right; (0, 1, 0, 1) represents the whole screen.Changes the portion of the framebuffer this
DisplayRegion
corresponds to. The parameters range from 0 to 1, where 0,0 is the lower left corner and 1,1 is the upper right; (0, 1, 0, 1) represents the whole screen.Changes the portion of the framebuffer this
DisplayRegion
corresponds to. The parameters range from 0 to 1, where 0,0 is the lower left corner and 1,1 is the upper right; (0, 1, 0, 1) represents the whole screen.Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.
-
property
draw_callback
→ CallbackObject¶ - Getter
Returns the
CallbackObject
set bysetDrawCallback()
.- Setter
Sets the
CallbackObject
that will be notified when the contents ofDisplayRegion
is drawn during the draw traversal. This callback will be made during the draw thread.The draw traversal is responsible for actually issuing the commands to the graphics engine to draw primitives. Its job is to walk through the list of CullableObjects build up by the cull traversal, as quickly as possible, issuing the appropriate commands to draw each one.
At the time the draw traversal callback is made, the graphics state is in the initial state, and no projection matrix or modelview matrix is in effect. begin_scene() has not yet been called, and no objects have yet been drawn. However, the viewport has already been set to the appropriate part of the window, and the clear commands for this
DisplayRegion
(if any) have been issued.The callback is passed an instance of a
DisplayRegionDrawCallbackData
, which contains pointers to the current scene information, as well as the currentDisplayRegion
and GSG. The callback replaces the normal draw behavior, so if your callback does nothing, nothing in theDisplayRegion
will be drawn. If you wish the draw traversal to continue to draw the contents of thisDisplayRegion
, you must call cbdata->upcall() from your callback.
-
getBottom
(i: int) → float¶ Retrieves the y coordinate of the bottom edge of the rectangle within its
GraphicsOutput
. This number will be in the range [0..1].
-
getCamera
(current_thread: Thread) → NodePath¶ Returns the camera associated with this
DisplayRegion
, or an emptyNodePath
if no camera is associated.
-
static
getClassType
() → TypeHandle¶
-
getCullCallback
() → CallbackObject¶ Returns the
CallbackObject
set bysetCullCallback()
.
-
getCullTraverser
() → CullTraverser¶ Returns the
CullTraverser
that will be used to draw the contents of thisDisplayRegion
.
-
getDimensions
(i: int) → LVecBase4¶ Retrieves the coordinates of the DisplayRegion’s rectangle within its
GraphicsOutput
. These numbers will be in the range [0..1].
-
getDrawCallback
() → CallbackObject¶ Returns the
CallbackObject
set bysetDrawCallback()
.
-
getIncompleteRender
() → bool¶ Returns the incomplete_render flag. See
setIncompleteRender()
.
-
getLeft
(i: int) → float¶ Retrieves the x coordinate of the left edge of the rectangle within its
GraphicsOutput
. This number will be in the range [0..1].
-
getLensIndex
() → int¶ Returns the specific lens of the associated Camera that will be used for rendering this scene. Most Cameras hold only one lens, but for multiple lenses this method may be used to selected between them.
-
getNumRegions
() → int¶ Returns the number of regions, see
setNumRegions()
.
-
getPipe
() → GraphicsPipe¶ Returns the
GraphicsPipe
that thisDisplayRegion
is ultimately associated with, or NULL if no pipe is associated.
-
getPixelHeight
(i: int) → int¶ Returns the height of the
DisplayRegion
in pixels.
-
getPixelSize
(i: int) → LVecBase2i¶ Returns the size of the
DisplayRegion
in pixels.
-
getPixelWidth
(i: int) → int¶ Returns the width of the
DisplayRegion
in pixels.
-
getRight
(i: int) → float¶ Retrieves the x coordinate of the right edge of the rectangle within its
GraphicsOutput
. This number will be in the range [0..1].
-
getScissorEnabled
() → bool¶ Returns whether or not scissor testing is enabled for this region. The default is true, except for the overlay display region.
-
getScreenshot
() → Texture¶ Captures the most-recently rendered image from the framebuffer and returns it as a Texture, or NULL on failure.
-
getScreenshot
(image: PNMImage) → bool Captures the most-recently rendered image from the framebuffer into the indicated
PNMImage
. Returns true on success, false on failure.
-
getSort
() → int¶ Returns the sort value associated with the
DisplayRegion
.
-
getStereoChannel
() → StereoChannel¶ Returns whether the
DisplayRegion
is specified as the left or right channel of a stereo pair, or whether it is a normal, monocular image. SeesetStereoChannel()
.
-
getTargetTexPage
() → int¶ Returns the target page number associated with this particular
DisplayRegion
, or -1 if it is not associated with a page. SeesetTargetTexPage()
.
-
getTexViewOffset
() → int¶ Returns the current texture view offset for this
DisplayRegion
. This is normally set to zero. If nonzero, it is used to select a particular view of any multiview textures that are rendered within thisDisplayRegion
.For a
StereoDisplayRegion
, this is normally 0 for the left eye, and 1 for the right eye, to support stereo textures.
-
getTextureReloadPriority
() → int¶ Returns the priority which is assigned to asynchronous texture reload requests. See
setTextureReloadPriority()
.
-
getTop
(i: int) → float¶ Retrieves the y coordinate of the top edge of the rectangle within its
GraphicsOutput
. This number will be in the range [0..1].
-
getWindow
() → GraphicsOutput¶ Returns the
GraphicsOutput
that thisDisplayRegion
is ultimately associated with, or NULL if no window is associated.
-
property
incomplete_render
→ bool¶ - Getter
Returns the incomplete_render flag. See
setIncompleteRender()
.- Setter
Sets the incomplete_render flag. When this is true, the frame will be rendered even if some of the geometry or textures in the scene are not available (e.g. they have been temporarily paged out). When this is false, the frame will be held up while this data is reloaded.
This flag may also be set on the
GraphicsStateGuardian
. It will be considered true for a givenDisplayRegion
only if it is true on both the GSG and on theDisplayRegion
.See
GraphicsStateGuardian.setIncompleteRender()
for more detail.
-
isActive
() → bool¶ Returns the active flag associated with the
DisplayRegion
.
-
isStereo
() → bool¶ Returns true if this is a
StereoDisplayRegion
, false otherwise.
-
property
lens_index
→ int¶ - Getter
Returns the specific lens of the associated Camera that will be used for rendering this scene. Most Cameras hold only one lens, but for multiple lenses this method may be used to selected between them.
- Setter
Sets the lens index, allows for multiple lenses to be attached to a camera. This is useful for a variety of setups, such as fish eye rendering. The default is 0.
Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.
-
makeCullResultGraph
() → PandaNode¶ Returns a special scene graph constructed to represent the results of the last frame’s cull operation.
This will be a hierarchy of nodes, one node for each bin, each of which will in term be a parent of a number of
GeomNodes
, representing the geometry drawn in each bin.This is useful mainly for high-level debugging and abstraction tools; it should not be mistaken for the low-level cull result itself, which is constructed and maintained internally. No such scene graph is normally constructed during the rendering of a frame; this is an artificial construct created for the purpose of making it easy to analyze the results of the cull operation.
-
static
makeScreenshotFilename
(prefix: str) → Filename¶ Synthesizes a suitable default filename for passing to
saveScreenshot()
.The default filename is generated from the supplied prefix and from the Config variable screenshot-filename, which contains the following strings:
%~p - the supplied prefix %~f - the frame count %~e - the value of screenshot-extension All other % strings in strftime().
-
property
pipe
→ GraphicsPipe¶ Returns the
GraphicsPipe
that thisDisplayRegion
is ultimately associated with, or NULL if no pipe is associated.
-
property
pixel_size
→ LVecBase2i¶ Returns the size of the
DisplayRegion
in pixels.
-
saveScreenshot
(filename: Filename, image_comment: str) → bool¶ Saves a screenshot of the region to the indicated filename. Returns true on success, false on failure.
-
saveScreenshotDefault
(prefix: str) → Filename¶ Saves a screenshot of the region to a default filename, and returns the filename, or empty string if the screenshot failed. The filename is generated by
makeScreenshotFilename()
.
-
property
scissor_enabled
→ bool¶ - Getter
Returns whether or not scissor testing is enabled for this region. The default is true, except for the overlay display region.
- Setter
Sets whether or not scissor testing is enabled for this region. The default is true, except for the overlay display region.
-
setActive
(active: bool) → None¶ Sets the active flag associated with the
DisplayRegion
. If theDisplayRegion
is marked inactive, nothing is rendered.Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.
-
setCamera
(camera: NodePath) → None¶ Sets the camera that is associated with this
DisplayRegion
. There is a one-to-many association between cameras andDisplayRegions
; one camera may be shared by multipleDisplayRegions
.The camera is actually set via a
NodePath
, which clarifies which instance of the camera (if there happen to be multiple instances) we should use.Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.
-
setCubeMapIndex
(cube_map_index: int) → None¶ Deprecated; replaced by
setTargetTexPage()
.
-
setCullCallback
(object: CallbackObject) → None¶ Sets the
CallbackObject
that will be notified when theDisplayRegion
is visited during the cull traversal. This callback will be made during the cull thread.The cull traversal is responsible for determining which nodes are visible and within the view frustum, and for accumulating state and transform, and generally building up the list of CullableObjects that are to be eventually passed to the draw traversal for rendering.
At the time the cull traversal callback is made, the traversal for this
DisplayRegion
has not yet started.The callback is passed an instance of a
DisplayRegionCullCallbackData
, which contains pointers to the current scene information, as well as the currentDisplayRegion
and GSG. The callback replaces the normal cull behavior, so if your callback does nothing, the scene graph will not be traversed and therefore nothing will be drawn. If you wish the normal cull traversal to be performed for thisDisplayRegion
, you must call cbdata->upcall() from your callback.
-
setCullTraverser
(trav: CullTraverser) → None¶ Specifies the
CullTraverser
that will be used to draw the contents of thisDisplayRegion
. Normally the defaultCullTraverser
is sufficient, but this may be changed to change the default cull behavior.
-
setDimensions
(dimensions: LVecBase4) → None¶ Changes the portion of the framebuffer this
DisplayRegion
corresponds to. The parameters range from 0 to 1, where 0,0 is the lower left corner and 1,1 is the upper right; (0, 1, 0, 1) represents the whole screen.
-
setDimensions
(l: float, r: float, b: float, t: float) → None Changes the portion of the framebuffer this
DisplayRegion
corresponds to. The parameters range from 0 to 1, where 0,0 is the lower left corner and 1,1 is the upper right; (0, 1, 0, 1) represents the whole screen.
-
setDimensions
(i: int, dimensions: LVecBase4) → None Changes the portion of the framebuffer this
DisplayRegion
corresponds to. The parameters range from 0 to 1, where 0,0 is the lower left corner and 1,1 is the upper right; (0, 1, 0, 1) represents the whole screen.Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.
-
setDimensions
(i: int, l: float, r: float, b: float, t: float) → None Changes the portion of the framebuffer this
DisplayRegion
corresponds to. The parameters range from 0 to 1, where 0,0 is the lower left corner and 1,1 is the upper right; (0, 1, 0, 1) represents the whole screen.
-
setDrawCallback
(object: CallbackObject) → None¶ Sets the
CallbackObject
that will be notified when the contents ofDisplayRegion
is drawn during the draw traversal. This callback will be made during the draw thread.The draw traversal is responsible for actually issuing the commands to the graphics engine to draw primitives. Its job is to walk through the list of CullableObjects build up by the cull traversal, as quickly as possible, issuing the appropriate commands to draw each one.
At the time the draw traversal callback is made, the graphics state is in the initial state, and no projection matrix or modelview matrix is in effect. begin_scene() has not yet been called, and no objects have yet been drawn. However, the viewport has already been set to the appropriate part of the window, and the clear commands for this
DisplayRegion
(if any) have been issued.The callback is passed an instance of a
DisplayRegionDrawCallbackData
, which contains pointers to the current scene information, as well as the currentDisplayRegion
and GSG. The callback replaces the normal draw behavior, so if your callback does nothing, nothing in theDisplayRegion
will be drawn. If you wish the draw traversal to continue to draw the contents of thisDisplayRegion
, you must call cbdata->upcall() from your callback.
-
setIncompleteRender
(incomplete_render: bool) → None¶ Sets the incomplete_render flag. When this is true, the frame will be rendered even if some of the geometry or textures in the scene are not available (e.g. they have been temporarily paged out). When this is false, the frame will be held up while this data is reloaded.
This flag may also be set on the
GraphicsStateGuardian
. It will be considered true for a givenDisplayRegion
only if it is true on both the GSG and on theDisplayRegion
.See
GraphicsStateGuardian.setIncompleteRender()
for more detail.
-
setLensIndex
(index: int) → None¶ Sets the lens index, allows for multiple lenses to be attached to a camera. This is useful for a variety of setups, such as fish eye rendering. The default is 0.
Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.
-
setNumRegions
(i: int) → None¶ Sets the number of regions that this
DisplayRegion
indicates. Usually, this number is 1 (and it is always at least 1), and only the first is used for rendering. However, if more than one is provided, you may select which one to render into using a geometry shader (gl_ViewportIndex in GLSL).
-
setScissorEnabled
(scissor_enabled: bool) → None¶ Sets whether or not scissor testing is enabled for this region. The default is true, except for the overlay display region.
-
setSort
(sort: int) → None¶ Sets the sort value associated with the
DisplayRegion
. Within a window,DisplayRegions
will be rendered in order from the lowest sort value to the highest.Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.
-
setStereoChannel
(stereo_channel: StereoChannel) → None¶ Specifies whether the
DisplayRegion
represents the left or right channel of a stereo pair, or whether it is a normal, monocular image. This automatically adjusts the lens that is used to render to thisDisplayRegion
to its left or right eye, according to the lens’s stereo properties.When the
DisplayRegion
is attached to a stereo window (one for whichisStereo()
returns true), this also specifies which physical channel theDisplayRegion
renders to.Normally you would create at least two
DisplayRegions
for a stereo window, one for each of the left and right channels. The twoDisplayRegions
may share the same camera (and thus the same lens); this parameter is used to control the exact properties of the lens when it is used to render into thisDisplayRegion
.Also see the
StereoDisplayRegion
, which automates managing a pair of left/rightDisplayRegions
.An ordinary
DisplayRegion
may be set to SC_mono, SC_left, or SC_right. You may set SC_stereo only on aStereoDisplayRegion
.This call also resets tex_view_offset to its default value, which is 0 for the left eye or 1 for the right eye of a stereo display region, or 0 for a mono display region.
-
setTargetTexPage
(page: int) → None¶ This is a special parameter that is only used when rendering the faces of a cube map or multipage and/or multiview texture.
This sets up the
DisplayRegion
to render to the ith page and jth view of its associated texture(s); the value must be consistent with the range of values availble to the texture. A normalDisplayRegion
that is not associated with any particular page should be set to page -1 and view 0.This is particularly useful when rendering cube maps and/or stereo textures.
Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.
-
setTexViewOffset
(tex_view_offset: int) → None¶ Sets the current texture view offset for this
DisplayRegion
. This is normally set to zero. If nonzero, it is used to select a particular view of any multiview textures that are rendered within thisDisplayRegion
.For a
StereoDisplayRegion
, this is normally 0 for the left eye, and 1 for the right eye, to support stereo textures. This is set automatically when you callsetStereoChannel()
.
-
setTextureReloadPriority
(texture_reload_priority: int) → None¶ Specifies an integer priority which is assigned to any asynchronous texture reload requests spawned while processing this
DisplayRegion
. This controls which textures are loaded first when multiple textures need to be reloaded at once; it also controls the relative priority between asynchronous texture loads and asynchronous model or animation loads.Specifying a larger number here makes the textures rendered by this
DisplayRegion
load up first. This may be particularly useful to do, for instance, for theDisplayRegion
that renders the gui.
-
property
sort
→ int¶ - Getter
Returns the sort value associated with the
DisplayRegion
.- Setter
Sets the sort value associated with the
DisplayRegion
. Within a window,DisplayRegions
will be rendered in order from the lowest sort value to the highest.Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.
-
property
stereo
→ bool¶ Returns true if this is a
StereoDisplayRegion
, false otherwise.
-
property
stereo_channel
→ StereoChannel¶ - Getter
Returns whether the
DisplayRegion
is specified as the left or right channel of a stereo pair, or whether it is a normal, monocular image. SeesetStereoChannel()
.- Setter
Specifies whether the
DisplayRegion
represents the left or right channel of a stereo pair, or whether it is a normal, monocular image. This automatically adjusts the lens that is used to render to thisDisplayRegion
to its left or right eye, according to the lens’s stereo properties.When the
DisplayRegion
is attached to a stereo window (one for whichisStereo()
returns true), this also specifies which physical channel theDisplayRegion
renders to.Normally you would create at least two
DisplayRegions
for a stereo window, one for each of the left and right channels. The twoDisplayRegions
may share the same camera (and thus the same lens); this parameter is used to control the exact properties of the lens when it is used to render into thisDisplayRegion
.Also see the
StereoDisplayRegion
, which automates managing a pair of left/rightDisplayRegions
.An ordinary
DisplayRegion
may be set to SC_mono, SC_left, or SC_right. You may set SC_stereo only on aStereoDisplayRegion
.This call also resets tex_view_offset to its default value, which is 0 for the left eye or 1 for the right eye of a stereo display region, or 0 for a mono display region.
-
property
target_tex_page
→ int¶ - Getter
Returns the target page number associated with this particular
DisplayRegion
, or -1 if it is not associated with a page. SeesetTargetTexPage()
.- Setter
This is a special parameter that is only used when rendering the faces of a cube map or multipage and/or multiview texture.
This sets up the
DisplayRegion
to render to the ith page and jth view of its associated texture(s); the value must be consistent with the range of values availble to the texture. A normalDisplayRegion
that is not associated with any particular page should be set to page -1 and view 0.This is particularly useful when rendering cube maps and/or stereo textures.
Don’t call this in a downstream thread unless you don’t mind it blowing away other changes you might have recently made in an upstream thread.
-
property
tex_view_offset
→ int¶ - Getter
Returns the current texture view offset for this
DisplayRegion
. This is normally set to zero. If nonzero, it is used to select a particular view of any multiview textures that are rendered within thisDisplayRegion
.For a
StereoDisplayRegion
, this is normally 0 for the left eye, and 1 for the right eye, to support stereo textures.- Setter
Sets the current texture view offset for this
DisplayRegion
. This is normally set to zero. If nonzero, it is used to select a particular view of any multiview textures that are rendered within thisDisplayRegion
.For a
StereoDisplayRegion
, this is normally 0 for the left eye, and 1 for the right eye, to support stereo textures. This is set automatically when you callsetStereoChannel()
.
-
property
texture_reload_priority
→ int¶ - Getter
Returns the priority which is assigned to asynchronous texture reload requests. See
setTextureReloadPriority()
.- Setter
Specifies an integer priority which is assigned to any asynchronous texture reload requests spawned while processing this
DisplayRegion
. This controls which textures are loaded first when multiple textures need to be reloaded at once; it also controls the relative priority between asynchronous texture loads and asynchronous model or animation loads.Specifying a larger number here makes the textures rendered by this
DisplayRegion
load up first. This may be particularly useful to do, for instance, for theDisplayRegion
that renders the gui.
-
property
window
→ GraphicsOutput¶ Returns the
GraphicsOutput
that thisDisplayRegion
is ultimately associated with, or NULL if no window is associated.
-
property