# DisplayRegion

from pandac.PandaModules import DisplayRegion

Class : DisplayRegion
Description : 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:

DisplayRegion: DisplayRegionBase DrawableRegion
DisplayRegionBase: TypedReferenceCount
TypedReferenceCount: TypedObject ReferenceCount
TypedObject: MemoryBase
MemoryBase:
ReferenceCount: MemoryBase
DrawableRegion:

## Methods of DisplayRegion:

clearCullCallback
clearDrawCallback
getBottom
getCamera
getClassType
getCubeMapIndex
getCullCallback
getCullTraverser
getDimensions
getDrawCallback
getIncompleteRender
getLeft
getPipe
getPixelHeight
getPixelWidth
getRight
getScreenshot
getSort
getStereoChannel
getTextureReloadPriority
getTop
getWindow
isActive
isStereo
makeCullResultGraph
makeScreenshotFilename
output
saveScreenshot
saveScreenshotDefault
setActive
setCamera
setCubeMapIndex
setCullCallback
setCullTraverser
setDimensions
setDrawCallback
setIncompleteRender
setSort
setStereoChannel
setTextureReloadPriority

## Methods of DisplayRegionBase:

getClassType
output

## Methods of TypedReferenceCount:

getClassType

## Methods of TypedObject:

getClassType
getType
getTypeIndex
isExactType
isOfType

## Methods of ReferenceCount:

getClassType
getRefCount
ref
testRefCountIntegrity
testRefCountNonzero
unref

## Methods of DrawableRegion:

disableClears
getClearActive
getClearColor
getClearColorActive
getClearDepth
getClearDepthActive
getClearStencil
getClearStencilActive
getClearValue
getPixelFactor
getPixelZoom
getRenderbufferType
isAnyClearActive
setClearActive
setClearColor
setClearColorActive
setClearDepth
setClearDepthActive
setClearStencil
setClearStencilActive
setClearValue
setPixelZoom
supportsPixelZoom

## Constants in DrawableRegion:

RTPStencil | (RenderTexturePlane)
RTPDepthStencil | (RenderTexturePlane)
RTPColor | (RenderTexturePlane)
RTPAuxRgba0 | (RenderTexturePlane)
RTPAuxRgba1 | (RenderTexturePlane)
RTPAuxRgba2 | (RenderTexturePlane)
RTPAuxRgba3 | (RenderTexturePlane)
RTPAuxHrgba0 | (RenderTexturePlane)
RTPAuxHrgba1 | (RenderTexturePlane)
RTPAuxHrgba2 | (RenderTexturePlane)
RTPAuxHrgba3 | (RenderTexturePlane)
RTPAuxFloat0 | (RenderTexturePlane)
RTPAuxFloat1 | (RenderTexturePlane)
RTPAuxFloat2 | (RenderTexturePlane)
RTPAuxFloat3 | (RenderTexturePlane)
RTPDepth | (RenderTexturePlane)
RTPCOUNT | (RenderTexturePlane)

clearCullCallback void DisplayRegion::clear_cull_callback(void); Description: Removes the callback set by an earlier call to set_cull_callback().

clearDrawCallback void DisplayRegion::clear_draw_callback(void); Description: Removes the callback set by an earlier call to set_draw_callback().

getBottom float DisplayRegion::get_bottom(void) const; Description: Retrieves the y coordinate of the bottom edge of the rectangle within its GraphicsOutput. This number will be in the range [0..1].

getCamera NodePath DisplayRegion::get_camera(Thread *current_thread = ((get_current_thread()))) const; Description: Returns the camera associated with this DisplayRegion, or an empty NodePath if no camera is associated.

getClassType static TypeHandle DisplayRegion::get_class_type(void); Undocumented function.

getCubeMapIndex int DisplayRegion::get_cube_map_index(void) const; Description: Returns the cube map face index associated with this particular DisplayRegion, or -1 if it is not associated with a cube map. See set_cube_map_index().

getCullCallback CallbackObject *DisplayRegion::get_cull_callback(void) const; Description: Returns the CallbackObject set by set_cull_callback().

getCullTraverser CullTraverser *DisplayRegion::get_cull_traverser(void); Description: Returns the CullTraverser that will be used to draw the contents of this DisplayRegion.

getDimensions void DisplayRegion::get_dimensions(float &l, float &r, float &b, float &t) const; Description: Retrieves the coordinates of the DisplayRegion's rectangle within its GraphicsOutput. These numbers will be in the range [0..1].

getDrawCallback CallbackObject *DisplayRegion::get_draw_callback(void) const; Description: Returns the CallbackObject set by set_draw_callback().

getIncompleteRender bool DisplayRegion::get_incomplete_render(void) const; Description: Returns the incomplete_render flag. See set_incomplete_render().

getLeft float DisplayRegion::get_left(void) const; Description: Retrieves the x coordinate of the left edge of the rectangle within its GraphicsOutput. This number will be in the range [0..1].

getPipe GraphicsPipe *DisplayRegion::get_pipe(void) const; Description: Returns the GraphicsPipe that this DisplayRegion is ultimately associated with, or NULL if no pipe is associated.

getPixelHeight int DisplayRegion::get_pixel_height(void) const; Description: Returns the height of the DisplayRegion in pixels.

getPixelWidth int DisplayRegion::get_pixel_width(void) const; Description: Returns the width of the DisplayRegion in pixels.

getRight float DisplayRegion::get_right(void) const; Description: Retrieves the x coordinate of the right edge of the rectangle within its GraphicsOutput. This number will be in the range [0..1].

getScreenshot bool DisplayRegion::get_screenshot(PNMImage &image); Description: Captures the most-recently rendered image from the framebuffer into the indicated PNMImage. Returns true on success, false on failure.

getSort int DisplayRegion::get_sort(void) const; Description: Returns the sort value associated with the DisplayRegion.

getStereoChannel Lens::StereoChannel DisplayRegion::get_stereo_channel(void); Description: Returns whether the DisplayRegion is specified as the left or right channel of a stereo pair, or whether it is a normal, monocular image. See set_stereo_channel().

getTextureReloadPriority int DisplayRegion::get_texture_reload_priority(void) const; Description: Returns the priority which is assigned to asynchronous texture reload requests. See set_texture_reload_priority().

getTop float DisplayRegion::get_top(void) const; Description: 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 *DisplayRegion::get_window(void) const; Description: Returns the GraphicsOutput that this DisplayRegion is ultimately associated with, or NULL if no window is associated.

isActive bool DisplayRegion::is_active(void) const; Description: Returns the active flag associated with the DisplayRegion.

isStereo virtual bool DisplayRegion::is_stereo(void) const; Description: Returns true if this is a StereoDisplayRegion, false otherwise.

makeCullResultGraph virtual PointerTo< PandaNode > DisplayRegion::make_cull_result_graph(void); Description: 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.

makeScreenshotFilename static Filename DisplayRegion::make_screenshot_filename(string const &prefix = ("screenshot")); Description: Synthesizes a suitable default filename for passing to save_screenshot(). 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().

output virtual void DisplayRegion::output(ostream &out) const; Description:

saveScreenshot bool DisplayRegion::save_screenshot(Filename const &filename, string const &image_comment = ("")); Description: Saves a screenshot of the region to the indicated filename. Returns true on success, false on failure.

saveScreenshotDefault Filename DisplayRegion::save_screenshot_default(string const &prefix = ("screenshot")); Description: 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 make_screenshot_filename().

setActive virtual void DisplayRegion::set_active(bool active); Description: Sets the active flag associated with the DisplayRegion. If the DisplayRegion is marked inactive, nothing is rendered.

setCamera virtual void DisplayRegion::set_camera(NodePath const &camera); Description: Sets the camera that is associated with this DisplayRegion. There is a one-to-many association between cameras and DisplayRegions; one camera may be shared by multiple DisplayRegions. 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.

setCubeMapIndex virtual void DisplayRegion::set_cube_map_index(int cube_map_index); Description: This is a special parameter that is only used when rendering the faces of a cube map. Normally you should not need to set it directly. This sets up the DisplayRegion to render to the nth cube map face; the value must be between 0 and 5, inclusive. A normal DisplayRegion that is not associated with any particular cube map should be set to -1.

setCullCallback void DisplayRegion::set_cull_callback(CallbackObject *object); Description: Sets the CallbackObject that will be notified when the DisplayRegion 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 current DisplayRegion 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 this DisplayRegion, you must call cbdata->upcall() from your callback.

setCullTraverser virtual void DisplayRegion::set_cull_traverser(CullTraverser *trav); Description: Specifies the CullTraverser that will be used to draw the contents of this DisplayRegion. Normally the default CullTraverser is sufficient, but this may be changed to change the default cull behavior.

setDimensions virtual void DisplayRegion::set_dimensions(float l, float r, float b, float t); Description: 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 void DisplayRegion::set_draw_callback(CallbackObject *object); Description: Sets the CallbackObject that will be notified when the contents of DisplayRegion 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 current DisplayRegion and GSG. The callback *replaces* the normal draw behavior, so if your callback does nothing, nothing in the DisplayRegion will be drawn. If you wish the draw traversal to continue to draw the contents of this DisplayRegion, you must call cbdata->upcall() from your callback.

setIncompleteRender virtual void DisplayRegion::set_incomplete_render(bool incomplete_render); Description: 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 given DisplayRegion only if it is true on both the GSG and on the DisplayRegion. See GraphicsStateGuardian::set_incomplete_render() for more detail.

setSort virtual void DisplayRegion::set_sort(int sort); Description: 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.

setStereoChannel virtual void DisplayRegion::set_stereo_channel(Lens::StereoChannel stereo_channel); Description: 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 this DisplayRegion to its left or right eye, according to the lens's stereo properties. When the DisplayRegion is attached to a stereo window (one for which is_stereo() returns true), this also specifies which physical channel the DisplayRegion renders to. Normally you would create at least two DisplayRegions for a stereo window, one for each of the left and right channels. The two DisplayRegions 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 this DisplayRegion. Also see the StereoDisplayRegion, which automates managing a pair of left/right DisplayRegions. An ordinary DisplayRegion may be set to SC_mono, SC_left, or SC_right. You may set SC_stereo only on a StereoDisplayRegion.

setTextureReloadPriority virtual void DisplayRegion::set_texture_reload_priority(int texture_reload_priority); Description: 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 the DisplayRegion that renders the gui.

getClassType static TypeHandle DisplayRegionBase::get_class_type(void); Undocumented function.

output virtual void DisplayRegionBase::output(ostream &out) const = 0; Undocumented function.

getClassType static TypeHandle TypedReferenceCount::get_class_type(void); Undocumented function.

getClassType static TypeHandle TypedObject::get_class_type(void); Undocumented function.

getType virtual TypeHandle TypedObject::get_type(void) const = 0; Derived classes should override this function to return get_class_type().

getTypeIndex int TypedObject::get_type_index(void) const; Description: Returns the internal index number associated with this object's TypeHandle, a unique number for each different type. This is equivalent to get_type().get_index().

isExactType bool TypedObject::is_exact_type(TypeHandle handle) const; Description: Returns true if the current object is the indicated type exactly.

isOfType bool TypedObject::is_of_type(TypeHandle handle) const; Description: Returns true if the current object is or derives from the indicated type.

getClassType static TypeHandle ReferenceCount::get_class_type(void); Undocumented function.

getRefCount int ReferenceCount::get_ref_count(void) const; Description: Returns the current reference count.

ref void ReferenceCount::ref(void) const; Description: Explicitly increments the reference count. User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically. This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it.

testRefCountIntegrity bool ReferenceCount::test_ref_count_integrity(void) const; Description: Does some easy checks to make sure that the reference count isn't completely bogus. Returns true if ok, false otherwise.

testRefCountNonzero bool ReferenceCount::test_ref_count_nonzero(void) const; Description: Does some easy checks to make sure that the reference count isn't zero, or completely bogus. Returns true if ok, false otherwise.

unref bool ReferenceCount::unref(void) const; Description: Explicitly decrements the reference count. Note that the object will not be implicitly deleted by unref() simply because the reference count drops to zero. (Having a member function delete itself is problematic; plus, we don't have a virtual destructor anyway.) However, see the helper function unref_delete(). User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically. This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it. The return value is true if the new reference count is nonzero, false if it is zero.

disableClears virtual void DrawableRegion::disable_clears(void); Description: Disables both the color and depth clear. See set_clear_color_active and set_clear_depth_active.

getClearActive virtual bool DrawableRegion::get_clear_active(int n) const; Description: Gets the clear-active flag for any bitplane.

getClearColor LVecBase4f const &DrawableRegion::get_clear_color(void) const; Description: Returns the current clear color value. This is the value that will be used to clear the color buffer every frame, but only if get_clear_color_active() returns true. If get_clear_color_active() returns false, this is meaningless.

getClearColorActive bool DrawableRegion::get_clear_color_active(void) const; Description: Returns the current setting of the flag that indicates whether the color buffer should be cleared every frame. See set_clear_color_active().

getClearDepth float DrawableRegion::get_clear_depth(void) const; Description: Returns the current clear depth value. This is the value that will be used to clear the depth buffer every frame, but only if get_clear_depth_active() returns true. If get_clear_depth_active() returns false, this is meaningless.

getClearDepthActive bool DrawableRegion::get_clear_depth_active(void) const; Description: Returns the current setting of the flag that indicates whether the depth buffer should be cleared every frame. See set_clear_depth_active().

getClearStencil unsigned int DrawableRegion::get_clear_stencil(void) const; Description: Returns the current clear stencil value. This is the value that will be used to clear the stencil buffer every frame, but only if get_clear_stencil_active() returns true. If get_clear_stencil_active() returns false, this is meaningless.

getClearStencilActive bool DrawableRegion::get_clear_stencil_active(void) const; Description: Returns the current setting of the flag that indicates whether the color buffer should be cleared every frame. See set_clear_stencil_active().

getClearValue virtual LVecBase4f const &DrawableRegion::get_clear_value(int n) const; Description: Returns the clear value for any bitplane.

getPixelFactor float DrawableRegion::get_pixel_factor(void) const; Description: Returns the amount by which the height and width of the region will be scaled internally, based on the zoom factor set by set_pixel_zoom(). This will return 1.0 if the pixel_zoom was not set or if it is not being respected (for instance, because the underlying renderer doesn't support it--see supports_pixel_zoom).

getPixelZoom float DrawableRegion::get_pixel_zoom(void) const; Description: Returns the value set by set_pixel_zoom(), regardless of whether it is being respected or not. Also see get_pixel_factor().

getRenderbufferType static int DrawableRegion::get_renderbuffer_type(int plane); Description: Returns the RenderBuffer::Type that corresponds to a RenderTexturePlane.

isAnyClearActive virtual bool DrawableRegion::is_any_clear_active(void) const; Description: Returns true if any of the clear types (so far there are just color or depth) have been set active, or false if none of them are active and there is no need to clear.

setClearActive virtual void DrawableRegion::set_clear_active(int n, bool clear_aux_active); Description: Sets the clear-active flag for any bitplane.

setClearColor void DrawableRegion::set_clear_color(LVecBase4f const &color); Description: Sets the clear color to the indicated value. This is the value that will be used to clear the color buffer every frame, but only if get_clear_color_active() returns true. If get_clear_color_active() returns false, this is meaningless.

setClearColorActive void DrawableRegion::set_clear_color_active(bool clear_color_active); Description: Toggles the flag that indicates whether the color buffer should be cleared every frame. If this is true, the color buffer will be cleared to the color indicated by set_clear_color(); otherwise, it will be left alone.

setClearDepth void DrawableRegion::set_clear_depth(float depth); Description: Sets the clear depth to the indicated value. This is the value that will be used to clear the depth buffer every frame, but only if get_clear_depth_active() returns true. If get_clear_depth_active() returns false, this is meaningless.

setClearDepthActive void DrawableRegion::set_clear_depth_active(bool clear_depth_active); Description: Toggles the flag that indicates whether the depth buffer should be cleared every frame. If this is true, the depth buffer will be cleared to the depth value indicated by set_clear_depth(); otherwise, it will be left alone.

setClearStencil void DrawableRegion::set_clear_stencil(unsigned int stencil); Description: Sets the clear stencil to the indicated value. This is the value that will be used to clear the stencil buffer every frame, but only if get_clear_color_active() returns true. If get_clear_stencil_active() returns false, this is meaningless.

setClearStencilActive void DrawableRegion::set_clear_stencil_active(bool clear_stencil_active); Description: Toggles the flag that indicates whether the stencil buffer should be cleared every frame. If this is true, the stencil buffer will be cleared to the value indicated by set_clear_stencil(); otherwise, it will be left alone.

setClearValue virtual void DrawableRegion::set_clear_value(int n, LVecBase4f const &clear_value); Description: Sets the clear value for any bitplane.

setPixelZoom virtual void DrawableRegion::set_pixel_zoom(float pixel_zoom); Description: Sets the amount by which the pixels of the region are scaled internally when filling the image interally. Setting this number larger makes the pixels blockier, but may make the rendering faster, particularly for software renderers. Setting this number to 2.0 reduces the number of pixels that have to be filled by the renderer by a factor of 2.0. It doesn't make sense to set this lower than 1.0. It is possible to set this on either individual DisplayRegions or on overall GraphicsWindows, but you will get better performance for setting it on the window rather than its individual DisplayRegions. Also, you may not set it on a DisplayRegion that doesn't have both clear_color() and clear_depth() enabled. This property is only supported on renderers for which it is particularly useful--currently, this is the tinydisplay software renderer. Other kinds of renderers allow you to set this property, but ignore it.

supportsPixelZoom virtual bool DrawableRegion::supports_pixel_zoom(void) const; Description: Returns true if a call to set_pixel_zoom() will be respected, false if it will be ignored. If this returns false, then get_pixel_factor() will always return 1.0, regardless of what value you specify for set_pixel_zoom(). This may return false if the underlying renderer doesn't support pixel zooming, or if you have called this on a DisplayRegion that doesn't have both set_clear_color() and set_clear_depth() enabled.