# 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: ReferenceCount DrawableRegion
ReferenceCount:
DrawableRegion:

## Methods of DisplayRegion:

computePixels
computePixelsAllStages
getBottom
getCamera
getClassType
getClearDepthBetweenEyes
getCubeMapIndex
getDimensions
getLeft
getPipe
getPixelHeight
getPixels
getPixelWidth
getRegionPixels
getRegionPixelsI
getRight
getScreenshot
getSort
getStereoChannel
getTop
getWindow
isActive
makeScreenshotFilename
output
saveScreenshot
saveScreenshotDefault
setActive
setCamera
setClearDepthBetweenEyes
setCubeMapIndex
setDimensions
setSort
setStereoChannel

## Methods of ReferenceCount:

getClassType
getRefCount
ref
testRefCountIntegrity
testRefCountNonzero
unref

## Methods of DrawableRegion:

disableClears
getClearColor
getClearColorActive
getClearDepth
getClearDepthActive
getClearStencil
getClearStencilActive
isAnyClearActive
setClearColor
setClearColorActive
setClearDepth
setClearDepthActive
setClearStencil
setClearStencilActive

computePixels void DisplayRegion::compute_pixels(void); Description: Computes the pixel locations of the DisplayRegion within its window. The DisplayRegion will request the size from the window. Description: Computes the pixel locations of the DisplayRegion within its window, given the size of the window in pixels.

computePixelsAllStages void DisplayRegion::compute_pixels_all_stages(void); Description: Computes the pixel locations of the DisplayRegion within its window. The DisplayRegion will request the size from the window. Description: Performs a compute_pixels() operation for all stages of the pipeline. This is appropriate, for instance, when a window changes sizes, since this is a global operation; and you want the new window size to be immediately available even to the downstream stages.

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.

getClearDepthBetweenEyes bool DisplayRegion::get_clear_depth_between_eyes(void) const; Description: Returns whether the depth buffer is cleared again between the left and right eyes of a stereo DisplayRegion. See set_clear_depth_between_eyes().

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

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

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.

getPixels void DisplayRegion::get_pixels(int &pl, int &pr, int &pb, int &pt) const; Description: Retrieves the coordinates of the DisplayRegion within its window, in pixels.

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

getRegionPixels void DisplayRegion::get_region_pixels(int &xo, int &yo, int &w, int &h) const; Description: Retrieves the coordinates of the DisplayRegion within its window, as the pixel location of its bottom-left corner, along with a pixel width and height.

getRegionPixelsI void DisplayRegion::get_region_pixels_i(int &xo, int &yo, int &w, int &h) const; Description: Similar to get_region_pixels(), but returns the upper left corner, and the pixel numbers are numbered from the top-left corner down, in the DirectX way of things.

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

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.

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

setClearDepthBetweenEyes void DisplayRegion::set_clear_depth_between_eyes(bool clear_depth_between_eyes); Description: Specifies whether the depth buffer is cleared again between the left and right eyes of a stereo DisplayRegion. This has an effect only when get_stereo_channel() returns Lens::SC_stereo; other kinds of DisplayRegions are monocular and do not render two different eyes. Normally, you want this to be true, since if you're using a depth buffer you normally need to clear it between the left and right eyes.

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

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

setSort 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 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. See set_stereo_channel(). This controls which direction--to the left or the right--the view from a PerspectiveLens is shifted when it is used to render into this DisplayRegion. Also see Lens::set_interocular_distance() and Lens::set_convergence_distance(). 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. When the DisplayRegion is attached to a stereo window (one in which FrameBufferProperties::FM_stereo is set), this also specifies which physical channel the DisplayRegion renders to.

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 void DrawableRegion::disable_clears(void); Description: Disables both the color and depth clear. See set_clear_color_active and set_clear_depth_active.

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

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

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.