# ParasiteBuffer

from pandac.PandaModules import ParasiteBuffer

Class : ParasiteBuffer
Description : This is a special GraphicsOutput type that acts a lot like a GraphicsBuffer, effectively allowing rendering to an offscreen buffer, except it does not create any framebuffer space for itself. Instead, it renders into the framebuffer owned by some other GraphicsOutput.
The x_size and y_size must therefore fit within the bounds of the source GraphicsOutput.
Since the framebuffer will be subsequently cleared when the actual owner draws in it later, this only makes sense if we are going to copy the contents of the framebuffer to a texture immediately after we draw it. Thus, has_texture() is implicitly true for a ParasiteBuffer.
This class is useful to render offscreen to a texture while preventing the waste of framebuffer memory for API's that are unable to render directly into a texture (and must render into a separate framebuffer first and then copy to texture). It is also the only way to render to a texture on API's that do not support offscreen rendering.

## Inheritance:

ParasiteBuffer: GraphicsOutput
GraphicsOutput: TypedWritableReferenceCount DrawableRegion
TypedWritableReferenceCount: TypedWritable ReferenceCount
TypedWritable: TypedObject
TypedObject:
ReferenceCount:
DrawableRegion:

## Methods of ParasiteBuffer:

getClassType

## Methods of GraphicsOutput:

addRenderTexture
clearDeleteFlag
clearRenderTextures
countTextures
getActiveDisplayRegion
getClassType
getDeleteFlag
getDisplayRegion
getFbProperties
getGsg
getInverted
getLeftEyeColorMask
getName
getNumActiveDisplayRegions
getNumDisplayRegions
getOneShot
getPipe
getRedBlueStereo
getRightEyeColorMask
getRtmMode
getScreenshot
getSort
getTexture
getTextureCard
getTexturePlane
getXSize
getYSize
hasSize
hasTexture
isActive
isStereo
isValid
makeCubeMap
makeDisplayRegion
makeScreenshotFilename
makeTextureBuffer
removeAllDisplayRegions
removeDisplayRegion
saveScreenshot
saveScreenshotDefault
setActive
setInverted
setOneShot
setRedBlueStereo
setSort
setupRenderTexture
triggerCopy

## Methods of TypedWritableReferenceCount:

getClassType

## Methods of TypedWritable:

getClassType

## Methods of TypedObject:

getClassType
getType
getTypeIndex
isExactType
isOfType

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

## Constants in GraphicsOutput:

RTMNone | (RenderTextureMode)
RTMBindOrCopy | (RenderTextureMode)
RTMCopyTexture | (RenderTextureMode)
RTMCopyRam | (RenderTextureMode)
RTMTriggeredCopyTexture | (RenderTextureMode)
RTMTriggeredCopyRam | (RenderTextureMode)
RTPColor | (RenderTexturePlane)
RTPDepth | (RenderTexturePlane)
RTPStencil | (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)
RTPCOUNT | (RenderTexturePlane)
FMRender | (FrameMode)
FMParasite | (FrameMode)
FMRefresh | (FrameMode)

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

addRenderTexture void GraphicsOutput::add_render_texture(Texture *tex, GraphicsOutput::RenderTextureMode mode, GraphicsOutput::RenderTexturePlane bitplane = (RTP_COUNT)); Description: Creates a new Texture object, suitable for rendering the contents of this buffer into, and appends it to the list of render textures. If tex is not NULL, it is the texture that will be set up for rendering into; otherwise, a new Texture object will be created, in which case you may call get_texture() to retrieve the new texture pointer. You can specify a bitplane to attach the texture to. the legal choices are: * RTP_depth * RTP_stencil * RTP_color * RTP_aux_rgba_0 * RTP_aux_rgba_1 * RTP_aux_rgba_2 * RTP_aux_rgba_3 If you do not specify a bitplane to attach the texture to, this routine will use a default based on the texture's format: * F_depth_component attaches to RTP_depth * F_stencil_index attaches to RTP_stencil * all other formats attach to RTP_color. The texture's format will be changed to match the format of the bitplane to which it is attached. For example, if you pass in an F_rgba texture and order that it be attached to RTP_depth, it will turn into an F_depth_component texture. Also see make_texture_buffer(), which is a higher-level interface for preparing render-to-a-texture mode.

clearDeleteFlag void GraphicsOutput::clear_delete_flag(void); Description: Resets the delete flag, so the GraphicsOutput will not be automatically deleted before the beginning of the next frame.

clearRenderTextures void GraphicsOutput::clear_render_textures(void); Description: If the GraphicsOutput is currently rendering to a texture, then all textures are dissociated from the GraphicsOuput.

countTextures int GraphicsOutput::count_textures(void) const; Description: If the GraphicsOutput is set to render into a texture, returns the number of textures that are being rendered into. Normally, the textures would be associated with different buffers - a color texture, a depth texture, and a stencil texture.

getActiveDisplayRegion PointerTo< DisplayRegion > GraphicsOutput::get_active_display_region(int n) const; Description: Returns the nth active DisplayRegion of those that have been created within the window. This may return NULL if n is out of bounds; particularly likely if the number of display regions has changed since the last call to get_num_active_display_regions().

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

getDeleteFlag bool GraphicsOutput::get_delete_flag(void) const; Description: Returns the current setting of the delete flag. When this is true, the GraphicsOutput will automatically be removed before the beginning of the next frame by the GraphicsEngine.

getDisplayRegion PointerTo< DisplayRegion > GraphicsOutput::get_display_region(int n) const; Description: Returns the nth DisplayRegion of those that have been created within the window. This may return NULL if n is out of bounds; particularly likely if the number of display regions has changed since the last call to get_num_display_regions().

getFbProperties FrameBufferProperties &GraphicsOutput::get_fb_properties(void); Description: Returns the framebuffer properties of the window.

getGsg GraphicsStateGuardian *GraphicsOutput::get_gsg(void) const; Filename: graphicsOutput.I Created by: drose (06Feb04) PANDA 3D SOFTWARE Copyright (c) 2001 - 2004, Disney Enterprises, Inc. All rights reserved All use of this software is subject to the terms of the Panda 3d Software license. You should have received a copy of this license along with this source code; you will also find a current copy of the license at http://etc.cmu.edu/panda3d/docs/license/ . To contact the maintainers of this program write to panda3d-general@lists.sourceforge.net . Description: Returns the GSG that is associated with this window. There is a one-to-one association between windows and GSG's. This may return NULL if the graphics context has not yet been created for the window, e.g. before the first frame has rendered; or after the window has been closed.

getInverted bool GraphicsOutput::get_inverted(void) const; Description: Returns the current setting of the inverted flag. When this is true, the scene is rendered into the window upside-down, flipped like a mirror along the X axis. See set_inverted().

getLeftEyeColorMask unsigned int GraphicsOutput::get_left_eye_color_mask(void) const; Description: Returns the color mask in effect when rendering a left-eye view in red_blue stereo mode. This is one or more bits defined in ColorWriteAttrib::Channels. See set_red_blue_stereo().

getName string const &GraphicsOutput::get_name(void) const; Description: Returns the name that was passed to the GraphicsOutput constructor.

getNumActiveDisplayRegions int GraphicsOutput::get_num_active_display_regions(void) const; Description: Returns the number of active DisplayRegions that have been created within the window.

getNumDisplayRegions int GraphicsOutput::get_num_display_regions(void) const; Description: Returns the number of DisplayRegions that have been created within the window, active or otherwise.

getOneShot bool GraphicsOutput::get_one_shot(void) const; Description: Returns the current setting of the one-shot flag. When this is true, the GraphicsOutput will automatically detach its texture (if it has one) and remove itself from the GraphicsEngine after it renders the next frame.

getPipe GraphicsPipe *GraphicsOutput::get_pipe(void) const; Description: Returns the GraphicsPipe that this window is associated with. It is possible that the GraphicsPipe might have been deleted while an outstanding PT(GraphicsOutput) prevented all of its children windows from also being deleted; in this unlikely case, get_pipe() may return NULL.

getRedBlueStereo bool GraphicsOutput::get_red_blue_stereo(void) const; Description: Returns whether red-blue stereo mode is in effect for this particular window. See set_red_blue_stereo().

getRightEyeColorMask unsigned int GraphicsOutput::get_right_eye_color_mask(void) const; Description: Returns the color mask in effect when rendering a right-eye view in red_blue stereo mode. This is one or more bits defined in ColorWriteAttrib::Channels. See set_red_blue_stereo().

getRtmMode GraphicsOutput::RenderTextureMode GraphicsOutput::get_rtm_mode(int i = (0)) const; Description: Returns the RenderTextureMode associated with the nth render-texture. Returns RTM_none if there is no such texture.

getScreenshot bool GraphicsOutput::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 GraphicsOutput::get_sort(void) const; Description: Returns the sorting order of this particular GraphicsOutput. The various GraphicsOutputs within a particular thread will be rendered in the indicated order.

getTexture Texture *GraphicsOutput::get_texture(int i = (0)) const; Description: Returns the nth texture into which the GraphicsOutput renders. Returns NULL if there is no such texture. If the texture is non-NULL, it may be applied to geometry to be rendered for any other windows or outputs that share the same GSG as this GraphicsOutput. The effect is undefined for windows that share a different GSG; usually in these cases the texture will be invalid.

getTextureCard NodePath GraphicsOutput::get_texture_card(void); Description: Returns a PandaNode containing a square polygon. The dimensions are (-1,0,-1) to (1,0,1). The texture coordinates are such that the texture of this GraphicsOutput is aligned properly to the polygon. The GraphicsOutput promises to surgically update the Geom inside the PandaNode if necessary to maintain this invariant. Each invocation of this function returns a freshly- allocated PandaNode. You can therefore safely modify the RenderAttribs of the PandaNode. The PandaNode is initially textured with the texture of this GraphicOutput.

getTexturePlane GraphicsOutput::RenderTexturePlane GraphicsOutput::get_texture_plane(int i = (0)) const; Description: Returns the RenderTexturePlane associated with the nth render-texture. Returns 0 if there is no such texture.

getXSize int GraphicsOutput::get_x_size(void) const; Description: Returns the width of the graphics frame buffer, if it is known. In certain cases (e.g. fullscreen windows), the size may not be known until after the object has been fully created. Check has_size() first. Certain objects (like windows) may change size spontaneously; this method is not thread-safe. To get the size of a window in a thread-safe manner, query get_properties().

getYSize int GraphicsOutput::get_y_size(void) const; Description: Returns the height of the graphics frame buffer, if it is known. In certain cases (e.g. fullscreen windows), the size may not be known until after the object has been fully created. Check has_size() first. Certain objects (like windows) may change size spontaneously; this method is not thread-safe. To get the size of a window in a thread-safe manner, query get_properties().

hasSize bool GraphicsOutput::has_size(void) const; Description: Returns true if the size of the window/frame buffer is known, false otherwise. In certain cases the size may not be known until after the object has been fully created. Also, certain objects (like windows) may change size spontaneously.

hasTexture bool GraphicsOutput::has_texture(void) const; Description: Returns true if the GraphicsOutput is rendering into any textures at all.

isActive virtual bool GraphicsOutput::is_active(void) const; Description: Returns true if the window is ready to be rendered into, false otherwise.

isStereo bool GraphicsOutput::is_stereo(void) const; Description: Returns Returns true if this window can render stereo DisplayRegions, either through red-blue stereo (see set_red_blue_stereo()) or through true hardware stereo rendering.

isValid bool GraphicsOutput::is_valid(void) const; Description: Returns true if the output is fully created and ready for rendering, false otherwise.

makeCubeMap GraphicsOutput *GraphicsOutput::make_cube_map(string const &name, int size, NodePath &camera_rig, BitMask< unsigned int, 32 > camera_mask = ((get_all_camera_mask())), bool to_ram = (0)); Description: This is similar to make_texture_buffer() in that it allocates a separate buffer suitable for rendering to a texture that can be assigned to geometry in this window, but in this case, the buffer is set up to render the six faces of a cube map. The buffer is automatically set up with six display regions and six cameras, each of which are assigned the indicated draw_mask and parented to the given camera_rig node (which you should then put in your scene to render the cube map from the appropriate point of view). You may take the texture associated with the buffer and apply it to geometry, particularly with TexGenAttrib::M_world_cube_map also in effect, to apply a reflection of everything seen by the camera rig.

makeDisplayRegion DisplayRegion *GraphicsOutput::make_display_region(void); Description: Creates a new DisplayRegion that covers the entire window. Description: Creates a new DisplayRegion that covers the indicated sub-rectangle within the window. The range on all parameters is 0..1.

makeScreenshotFilename static Filename GraphicsOutput::make_screenshot_filename(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 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().

makeTextureBuffer GraphicsOutput *GraphicsOutput::make_texture_buffer(string const &name, int x_size, int y_size, Texture *tex = ((void *)(0)), bool to_ram = (0)); Description: Creates and returns an offscreen buffer for rendering into, the result of which will be a texture suitable for applying to geometry within the scene rendered into this window. If tex is not NULL, it is the texture that will be set up for rendering into; otherwise, a new Texture object will be created. In either case, the target texture can be retrieved from the return value with buffer->get_texture() (assuming the return value is not NULL). If to_ram is true, the buffer will be set up to download its contents to the system RAM memory associated with the Texture object, instead of keeping it strictly within texture memory; this is much slower, but it allows using the texture with any GSG. This will attempt to be smart about maximizing render performance while minimizing framebuffer waste. It might return a GraphicsBuffer set to render directly into a texture, if possible; or it might return a ParasiteBuffer that renders into this window. The return value is NULL if the buffer could not be created for some reason. When you are done using the buffer, you should remove it with a call to GraphicsEngine::remove_window() (or set the one_shot flag so it removes itself after one frame).

removeAllDisplayRegions void GraphicsOutput::remove_all_display_regions(void); Description: Removes all display regions from the window, except the default one that is created with the window.

removeDisplayRegion bool GraphicsOutput::remove_display_region(DisplayRegion *display_region); Description: Removes the indicated DisplayRegion from the window, and destructs it if there are no other references. Returns true if the DisplayRegion is found and removed, false if it was not a part of the window.

saveScreenshot bool GraphicsOutput::save_screenshot(Filename const &filename, string const &image_comment = ("")); Description: Saves a screenshot of the region to the indicated filename. The image comment is an optional user readable string that will be saved with the header of the image (if the file format supports embedded data; for example jpg allows comments). Returns true on success, false on failure.

saveScreenshotDefault Filename GraphicsOutput::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 GraphicsOutput::set_active(bool active); Description: Sets the active flag associated with the GraphicsOutput. If the GraphicsOutput is marked inactive, nothing is rendered.

setInverted void GraphicsOutput::set_inverted(bool inverted); Description: Changes the current setting of the inverted flag. When this is true, the scene is rendered into the window upside-down and backwards, that is, inverted as if viewed through a mirror placed on the floor. This is primarily intended to support DirectX (and a few buggy OpenGL graphics drivers) that perform a framebuffer-to-texture copy upside-down from the usual OpenGL (and Panda) convention. Panda will automatically set this flag for offscreen buffers on hardware that is known to do this, to compensate when rendering offscreen into a texture.

setOneShot void GraphicsOutput::set_one_shot(bool one_shot); Description: Changes the current setting of the one-shot flag. When this is true, the GraphicsOutput will automatically detach its texture (if it has one) and remove itself from the GraphicsEngine after it renders the next frame.

setRedBlueStereo void GraphicsOutput::set_red_blue_stereo(bool red_blue_stereo, unsigned int left_eye_color_mask, unsigned int right_eye_color_mask); Description: Enables red-blue stereo mode on this particular window. When red-blue stereo mode is in effect, DisplayRegions that have the "left" channel set will render in the red (or specified) channel only, while DisplayRegions that have the "right" channel set will render in the blue (or specified) channel only. The remaining two parameters specify the particular color channel(s) to associate with each eye. Use the bits defined in ColorWriteAttrib::Channels. This can be used to achieve a cheesy stereo mode in the absence of hardware-supported stereo.

setSort void GraphicsOutput::set_sort(int sort); Description: Adjusts the sorting order of this particular GraphicsOutput, relative to other GraphicsOutputs.

setupRenderTexture void GraphicsOutput::setup_render_texture(Texture *tex, bool allow_bind, bool to_ram); Description: This is a deprecated interface that made sense back when GraphicsOutputs could only render into one texture at a time. From now on, use clear_render_textures and add_render_texture instead.

triggerCopy void GraphicsOutput::trigger_copy(void); Description: When the GraphicsOutput is in triggered copy mode, this function triggers the copy (at the end of the next frame).

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

getClassType static TypeHandle TypedWritable::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 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.