Rhino C++ API
8.17
|
#include <RhinoSdkDisplayConduit.h>
Static Public Member Functions | |
static CRhinoDisplayConduit * | FromRuntimeSerialNumber (unsigned int display_conduit_sn) |
static bool | IsValidDisplayConduitPointer (const void *display_conduit) |
static bool | IsValidDisplayConduitReference (const CRhinoDisplayConduit &display_conduit) |
static unsigned int | RuntimeSerialNumber (const CRhinoDisplayConduit *conduit) |
Protected Attributes | |
const CSupportChannels | m_Channels |
The channels that this class was constructed with. More... | |
class CChannelAttributes * | m_pChannelAttrs = nullptr |
CDisplayPipelineAttributes * | m_pDisplayAttrs = nullptr |
unsigned int | m_rhino_doc_sn = 0 |
unsigned int | m_rhino_view_sn = 0 |
unsigned int | m_rhino_viewport_sn = 0 |
Friends | |
class | CRhinoDisplayPipeline |
Display conduits provide support for adding custom display functionality during drawing inside of a display pipeline/viewport.
A subclass of a conduit specifies what channels or "phases" of drawing that it wants to be involved in.
Conduits may be "bound" to specific display pipelines or viewports which means that they will only operate with the objects they are bound to. If a binding is not defined, the conduit will operate in all display pipelines.
CRhinoDisplayConduit::CRhinoDisplayConduit | ( | CSupportChannels | channel_mask, |
bool | enable | ||
) |
Parameters: channel_mask: [in] Set of CSupportChannels that this conduit is interested in. enable: [in] Should the conduit initially be enabled? Remarks: Do not use SC_POSTPROCESSFRAMEBUFFER unless you absolutely need to. The display pipeline will check to see if it has any conduits that require this phase of drawing and will only perform a postprocess if one exists. Post processing of the frame buffer requires multiple dib copies at the end of drawing a frame and will cause a constant performance hit on display speed.
Since most of the time a conduit needs to only implement 1 to 2 channels at at time, it is also recommended that you do NOT use SC_ALL_CHANNELS to construct your conduit...This will make your counduit (and the pipeline) very inefficient. Example: If you had a conduit subclass that wanted to pay attention to object drawing and foreground drawing, you would set up the constructor as follows
CMyDisplayConduit::CMyDisplayConduit() : CRhinoDisplayConduit( CSupportChannels::SC_DRAWOBJECT | CSupportChannels::SC_DRAWFOREGROUND ) { ...set up some other class variables } ON_DEPRECATED - removing deprecation for the time being so we can find and clean up other outstanding warnings
CRhinoDisplayConduit::CRhinoDisplayConduit | ( | CSupportChannels | channel_mask | ) |
|
virtual |
bool CRhinoDisplayConduit::Bind | ( | const CRhinoDisplayPipeline & | pipeline | ) |
Binding methods...
Description: Bind this conduit to a display pipeline/viewport. If this conduit is already bound to another pipeline or viewport, that binding will not be removed and this conduit will be bound to multiple pipelines/viewports Returns: false if this conduit is already bound to the provided pipeline/viewport
bool CRhinoDisplayConduit::Bind | ( | const CRhinoView & | view | ) |
bool CRhinoDisplayConduit::Bind | ( | const CRhinoViewport & | viewport | ) |
bool CRhinoDisplayConduit::Bind | ( | const ON_Viewport & | viewport | ) |
int CRhinoDisplayConduit::BindingCount | ( | ) | const |
Description: Returns number of viewports that this conduit is bound to
bool CRhinoDisplayConduit::BindingsExist | ( | ) | const |
Description: Returns true if this conduit is bound to any specific viewport
bool CRhinoDisplayConduit::ChannelSupported | ( | UINT | channel | ) | const |
Attributes...
Parameters: channel: [in] CSupportChannel or a list of CSupportChannels that are or'd together Returns: True if this conduit supports given channel or list of channels. The supported channels are the ones that were defined in the conduit's constructor
bool CRhinoDisplayConduit::ConstantBinding | ( | ) | const |
Description:
void CRhinoDisplayConduit::Disable | ( | ) |
Description: Turn this conduit off. When a conduit is disabled, it will not participate in any custom drawing activity.
class CRhinoDoc* CRhinoDisplayConduit::Document | ( | ) | const |
unsigned int CRhinoDisplayConduit::DocumentSerialNumber | ( | ) | const |
Returns: The document that the conduit is working with at the time of ExecConduit. Remarks: The returned pointer may be null.
void CRhinoDisplayConduit::Enable | ( | ) |
Description: Turn this conduit on. When a conduit is enabled, it's ExecConduit function is called for each viewport that this conduit pays attention to. ON_DEPRECATED - removing deprecation for the time being so we can find and clean up other outstanding warnings
void CRhinoDisplayConduit::Enable | ( | unsigned int | docSerialNumber | ) |
void CRhinoDisplayConduit::EnableConstantBinding | ( | bool | enable = true | ) |
Description: When a conduit runs inside of a pipeline, it is said to be "bound" to that pipeline. By default all conduits are bound to all existing pipelines and any newly created ones...This is known as "constant binding"...If a conduit is only supposed to run/execute inside a specific pipeline/viewport (or set of viewports) then constant binding must be disabled, and the conduit must then be manually "bound" to a specific pipeline/viewport. See comments on all of "Bind()" methods.
Note: You can still bind conduits to specific pipelines/viewports, but the conduit will have to manually check for bindings inside of "ExecConduit()" using the "IsBound()" methods. By disabling constant binding and manually binding your conduit, will force your conduit to only run in specific pipelines/viewports (ie. no checks are necessary, they're handled by the pipeline).
Parameters: enable: [in] Set to false to disable constant binding, true to enable it.
|
pure virtual |
Operations...
Description: Conduits should/could be thought of as small pieces of code that get "executed" inside of Rhino's pipeline...and by specifying which "channel" your conduit executes in, allows you to determine where and when your code runs.
This function is called for every CSupportChannel that this conduit has been constructed with during the process of drawing a single frame. ExecConduit is not called when the conduit is disabled.
Parameters: pipeline: [in] the pipeline that is currently executing and calling this conduit. This is the pipeline you should be calling "Draw" functions on if you want to perform any custom drawing. channel: [in] This function can be called multiple times by a pipeline while drawing a single frame. The channel parameter specifies what part of CSupportChannels is currently being executed terminate: [out] Set this to true if you don't want other conduits to perform operations in the current channel after this function returns. Typically you will leave this parameter alone and allow other enabled conduits to perform their custom drawing code. Returns: True if the function completed successfully. If this function returns false, something bad occurred and drawing of the current frame stops.
Implemented in CRhinoGumballDisplayConduit.
|
static |
Parameters: display_conduit_sn - [in] Returns: If display_conduit_sn identifies an existing CRhinoDisplayConduit, then a pointer to that conduit is returned. Otherwise, null is returned.
unsigned int CRhinoDisplayConduit::GetGeometryFilter | ( | ) | const |
Description: Returns the current geometry filter set for this conduit. Possible values will be based on ON::object_type enum and the different combinations that can exist through or-ing ( | ) them together.
Note: If you passed 0 to SetGeometryFilter(), then this routine will return ON::any_object and not 0.
ON_UuidList CRhinoDisplayConduit::GetObjectFilter | ( | ) | const |
void CRhinoDisplayConduit::GetSelectedFilter | ( | bool & | on, |
bool & | checkSubObjects | ||
) | const |
Description: Get filter settings for selected objects. See SetSelectedFilter comments. Parameters: on - [out] true limits the conduit to selected objects checkSubObjects - [out] if true and on=true, then the conduit will be called for objects that have some subset of the object selected, like some edges of a surface.
bool CRhinoDisplayConduit::InterestedInObject | ( | const CRhinoObject * | ) | const |
Description: Determines if the passed in object's "type" matches the currently set geometry filter. This is more or less a helper function used when processing object-based channels.
Returns: true - if passed in object's type matches against the current geometry filter. false - if passed in object's type does NOT match against the currently geometry filter.
Note: If the current geometry filter is set to ON::any_object OR 0, this routine will always return true, and no conditions or comparisons are checked or made.
bool CRhinoDisplayConduit::IsBound | ( | const CRhinoDisplayPipeline & | pipeline, |
bool | ignore_state = false |
||
) | const |
Description: Determines if this conduit is bound to a specific pipeline or viewport Parameters: pipeline: [in] the pipeline to check binding against ignore_state: [in] determines if whether or not the "constant binding" state should be ignored. (See comments for "EnableConstantBinding()"). In other words, if this conduit is using constant binding (default), then it doesn't really matter if it is bound to anything since constant binding means "always bind to everything". However, most of the time it is necessary to pay attention to the state since conduits can be manually bound and programs need to know which pipelines this conduit is bound to. There are certain conditions where the display pipeline need not pay attention to the constant binding state, but most likely all other programs do...It is recommended that if you do not understand exactly what is going on here, that you just use the default.
bool CRhinoDisplayConduit::IsBound | ( | const CRhinoView & | view, |
bool | ignore_state = false |
||
) | const |
See: CRhinoDisplayConduit::IsBound( const CRhinoDisplayPipeline& pipeline, bool ignore_state = false) const;.
bool CRhinoDisplayConduit::IsBound | ( | const CRhinoViewport & | viewport, |
bool | ignore_state = false |
||
) | const |
See: CRhinoDisplayConduit::IsBound( const CRhinoDisplayPipeline& pipeline, bool ignore_state = false) const;.
bool CRhinoDisplayConduit::IsBound | ( | const ON_Viewport & | viewport, |
bool | ignore_state = false |
||
) | const |
See: CRhinoDisplayConduit::IsBound( const CRhinoDisplayPipeline& pipeline, bool ignore_state = false) const;.
bool CRhinoDisplayConduit::IsEnabled | ( | ) | const |
bool CRhinoDisplayConduit::IsEnabled | ( | unsigned int | docSerialNumber | ) | const |
|
static |
Parameters: display_conduit - [in] Returns: True if the display_conduit pointer is null or points to an existing CRhinoDisplayConduit.
|
static |
Parameters: display_conduit - [in] Returns: True if display_conduit refers to an existing CRhinoDisplayConduit.
|
virtual |
Notifications...
Description: Display pipelines will call this function when any of the actions defined in EConduitNotifiers occurs. This function is typically not overridden, but may be useful if you need to adjust internal data when different pipeline events occur. Parameters: notification_event: [in] the event reported by the display pipeline pipeline: [in] the display pipeline calling this conduit with the event notification.
class CRhinoPageView* CRhinoDisplayConduit::PageView | ( | ) | const |
unsigned int CRhinoDisplayConduit::PageViewSerialNumber | ( | ) | const |
Returns: The page view that the conduit is working with at the time of ExecConduit. Remarks: The returned pointer may be null.
bool CRhinoDisplayConduit::ReplaceBinding | ( | const CRhinoDisplayPipeline & | old_pipeline, |
const CRhinoDisplayPipeline & | new_pipeline | ||
) |
Description: Remove the binding for a pipeline or viewport and add a binding for a new pipeline or viewport Parameters: old_pipeline: [in] the pipeline that this conduit is removing a binding from new_pipeline: [in] the pipeline that this conduit is adding a binding to Returns: false if this conduit was not already bound to the pipeline or viewport that it is trying to replace
bool CRhinoDisplayConduit::ReplaceBinding | ( | const CRhinoView & | old_view, |
const CRhinoView & | new_view | ||
) |
bool CRhinoDisplayConduit::ReplaceBinding | ( | const CRhinoViewport & | old_viewport, |
const CRhinoViewport & | new_viewport | ||
) |
bool CRhinoDisplayConduit::ReplaceBinding | ( | const ON_Viewport & | old_viewport, |
const ON_Viewport & | new_viewport | ||
) |
|
static |
Description: Get the uniuqe runtime serial number for a given display conduit
void CRhinoDisplayConduit::SetGeometryFilter | ( | unsigned int | geometry_filter | ) |
Description: The geometry type filter controls which types of geometry (points, curves, surfaces, meshes, etc.) will be processed in any "object based" channels (see SC_OBJECT_BASED_CHANNEL)
Parameters: geometry_filter - [in] an unsigned int made by or-ing ( | ) values from the ON::object_type enum. However, If you pass 0, then this is interpreted as "no geometry filter", which means ALL geometry will be processed and is equivalent to passing the value ON::any_object.
Note: The default geometry filter for all conduits is ON::any_object. If you want your conduit to only process specific types of objects, then you must set the geometry filter for your conduit accordingly. Using ON::object_type might seem like overkill for this purpose (since not all types are technically "drawn" as objects within the channels), however, this is more consistent with how filtering works in other classes.
For example: If you have a conduit that executes in the SC_DRAWOBJECT channel, but you're only interested in processing "Light" objects, then you would set your conduit's geometry filter like so:
myConduit.SetGeometryFilter( ON::light_type );
...a good place to set this would be either in your conduit's constructor or just before you enable your conduit, depending on how you've decided to use this feature.
void CRhinoDisplayConduit::SetObjectFilter | ( | const ON_SimpleArray< ON_UUID > & | objectIds | ) |
void CRhinoDisplayConduit::SetObjectFilter | ( | ON_UUID | objectId | ) |
void CRhinoDisplayConduit::SetSelectedFilter | ( | bool | on, |
bool | checkSubObjects | ||
) |
Description: For the per-object drawing channels, allow a filter to only work with selected objects. Enabling the selected filter will cause the InterestedInObject function to return false for unselected objects
Parameters: on - [in] true limits the conduit to selected objects checkSubObjects - [in] if true and on=true, then the conduit will be called for objects that have some subset of the object selected, like some edges of a surface.
bool CRhinoDisplayConduit::ToggleBinding | ( | const CRhinoDisplayPipeline & | pipeline | ) |
Description: Flip binding state for a given pipeline / viewport Returns: Always returns true
bool CRhinoDisplayConduit::ToggleBinding | ( | const CRhinoView & | view | ) |
bool CRhinoDisplayConduit::ToggleBinding | ( | const CRhinoViewport & | viewport | ) |
bool CRhinoDisplayConduit::ToggleBinding | ( | const ON_Viewport & | viewport | ) |
bool CRhinoDisplayConduit::Unbind | ( | const CRhinoDisplayPipeline & | pipeline | ) |
Description: Remove a binding from a display pipeline/viewport. Returns: false if this conduit was not bound to the provided pipeline/viewport
bool CRhinoDisplayConduit::Unbind | ( | const CRhinoView & | view | ) |
bool CRhinoDisplayConduit::Unbind | ( | const CRhinoViewport & | viewport | ) |
bool CRhinoDisplayConduit::Unbind | ( | const ON_Viewport & | viewport | ) |
void CRhinoDisplayConduit::UnbindAll | ( | ) |
Description: Set this conduit to not be bound to any specific display pipeline or viewport
class CRhinoView* CRhinoDisplayConduit::View | ( | ) | const |
class CRhinoViewport* CRhinoDisplayConduit::Viewport | ( | ) | const |
unsigned int CRhinoDisplayConduit::ViewportSerialNumber | ( | ) | const |
Returns: The viewport that the conduit is working with at the time of ExecConduit. Remarks: The returned pointer may be null.
unsigned int CRhinoDisplayConduit::ViewSerialNumber | ( | ) | const |
Returns: The view that the conduit is working with at the time of ExecConduit. Remarks: The returned pointer may be null.
|
friend |
|
protected |
The channels that this class was constructed with.
|
protected |
Channel attributes are set up for each channel or "phase" of drawing. If the conduit modifies these attributes inside of the ExecConduit function, the display for the current channel will be changed based on these attributes. Note: See the definition of CChannelAttributes for a "logical grouping" of which attributes apply to which channels. Note2: Changing channel attributes that are not part of the "current channel" context will have unknown and unexpected results.
|
protected |
Global pipeline display attributes that the conduit can adjust to modify the display Note: Changing display attributes may have no effect based on which channel this conduit is currently running in (ie. The pipeline may step on any changes). A good rule is to only change these attributes inside SC_OBJECTDISPLAYATTRS, or all OBJECT DRAW channels, anywhere else may produce unexpected results.
|
protected |
Conduit parameters... Note: Each of these are set and assigned accordingly prior to calling "ExecConduit"... These pointers can change often. Do not hold onto them and use them outside the scope of the ExecConduit function The document that the conduit is working with at the time of ExecConduit Use CRhinoDisplayConduit.Document() to get a CRhinoDoc pointer.
|
protected |
The view that the conduit is working with at the time of ExecConduit Use CRhinoDisplayConduit.View() to get a CRhinoView pointer. Use CRhinoDisplayConduit.PageView() to get a CRhinoPageView pointer.
|
protected |
The viewport the conduit is working with at the time of ExecConduit Use CRhinoDisplayConduit.Viewport() to get a CRhinoViewport pointer.