|
HDK
|
Houdini offers several rendering hooks that allow you to augment or replace rendering in the Houdini viewport. There are two main types of hooks - primitive hooks, and scene hooks.
Primitive hooks execute rendering code based on specific primitives found within a displayed GU_Detail. They can be used to implement viewport rendering code for custom-designed primitives, add decorations and guides to existing primitives, or replace the Houdini rendering of a native primitive.
Scene hooks are not tied to any given geometry, and instead operate at the viewport level. They can do things such as render additional material to the beauty pass, draw in the overlay plane, or do a framebuffer effect such as a depth of field.
A primitive render hook is responsible for creating a GR_Primitive-based object for a certain primitive type (or types) in a GU_Detail. A primitive render hook is represented by GUI_PrimitiveHook. This class is only ever instantiated once.
GUI_PrimitiveHook's main function is to inspect GT or GEO primitives passed to it and decide whether to create a custom GR_Primitive for this primitive, or pass it along to other hooks or the native Houdini rendering method. A GUI_PrimitiveHook can:
A GUI_PrimitiveHook must be registered before it can be used. This is done in one of two ways, depending on whether it is being installed on a native or custom primitive.
A hook for a native primitive can be installed via the newRenderHook() function. The type ID for a native GT or GEO primitive is known from the header (GA_PrimitiveTypes.h or GT_PrimitiveTypes.h), so it can be installed directly:
A custom primitive's type ID is not known until it is registered, however, so any render hooks for this primitive must be registered when the GEO primitive is registered:
A GUI_PrimitiveHook must have a name for message reporting, and also a render mask which describes the renderers it supports. A render hook can support all GL renderers, a subset, or a single GL renderer. These are set using the bitfield GUI_RenderMask.
When installing GUI_PrimitiveHook, a priority and an optional GUI_PrimitiveHookFlags parameter can be specified. The priority defines the order that hooks defined for the same primitive type will see the primitive, with precedence given to larger numbers. Any signed integer except MIN_INT32 can be used as a priority value. The priority allows multiple primitive hooks to analyze a primitive, which is useful in cases where a hook may look for the existence of an attribute to render the primitive differently (eg. 'guide_hair' is 1).
The GUI_PrimitiveHookFlags parameter is a bitfield of flags:
Scene render hooks replace or augment render passes, and are not tied to any specific geometry. They allow you to render text in the viewport, apply effects to the beauty pass, draw your own background, or entirely replace the Houdini viewport.
To install a scene hook, derive a class from DM_SceneHook and DM_SceneRenderHook, then install it to a render pass.
The render passes are, in order of rendering:
DM_HOOK_BACKGROUND: The first element drawn to the viewport, without any camera transform applied (matrices set up to 1:1 pixel correspondence).DM_HOOK_PRE_RENDER: Elements drawn before the beauty pass, with a camera transform. The background image is drawn in the Houdini native pre-render pass.DM_HOOK_BEAUTY: All opaque user-generated geometry is drawn in this pass.DM_HOOK_BEAUTY_TRANSPARENT: Any transparent user-generated geometry is drawn in this pass, after the opaque beauty pass.DM_HOOK_UNLIT: Unlit (non-lit, non-shadowed) geometry is drawn in this pass. Guide and template geometries are a good example of what is drawn in this pass.DM_HOOK_XRAY: Objects with the X-ray flag set (such as bones) are drawn in this pass. Objects should only draw as wireframe in this pass.DM_HOOK_POST_RENDER: Elements drawn after all the scene geometry, but still with the camera transform, are drawn. The origin, field guide and safe area are drawn in the native Houdini post-render pass.DM_HOOK_FOREGROUND: The last elements drawn in the viewport. No native Houdini elements are drawn in this pass.A scene hook can be registered multiple times to different render passes. This can be used to bracket the native rendering, or use data from earlier passes later on. The hook is responsible for any sharing of the render hook between passes.
The pre-render to post-render passes are rendered per-stereo eye perspective, while the background and foreground passes are only rendered once. Not all passes are available in the UV viewport (no BEAUTY_TRANSPARENT, UNLIT or XRAY).
For the BEAUTY, BEAUTY_TRANSPARENT, UNLIT and XRAY passes in OBJ,SOPs, and DOPs, a list of the geometry that falls into these categories can be queried from DM_VPortAgent, which is passed to the render method. These are getOpaqueObject() (and getNumOpaqueObjects()) for the beauty pass, getTransparentObject() for the beauty transparent pass, getUnlitObject() for the unlit pass, and getXRayObject() for the xray pass. All except the xray object list are mutually exclusive.
For LOPs, only the display and current LOPs are available, which can be used to query the stage (LOP_Node::getCookedDataHandle() ) and inspect the scene as a whole.
There is a also a DM_HOOK_FULL_SCENE hook which allows all of the above to be replaced by a single hook.
For High Quality Lighting, two additional hooks are provided, with the light provided:
DM_HOOK_SHADOW: Shadow pass for generating a shadow map, or other lighting technique, for the light pass. Only computed when the light or user geometry changes. Only done when shadows are enabled.DM_HOOK_HQ_LIGHT_PASS: Per-light lighting pass. Additive blending is enabled when this hook is called, so only the lighting contribution for this light needs to be drawn.The RE_Light object is passed to both passes, and data can be stored on the RE_Light by using the attachUserData(), detachUserData(), and getAttachedUserData() methods (each of which takes an index, so that multiple data chunks can be attached by the same or different viewports). The @ RE_ShadowMap object for a light can also be accessed and rendered to or used in the lighting passes.
For selecting things within hooks, there are two type of picking hooks - a DM_HOOK_FRAMEBUFFER_PICK hook for single clicks and visible only, and a DM_HOOK_FRUSTUM_PICK for volume selection. This are active when doing component selection in SOPs or LOPs.
DM_HOOK_FRAMEBUFFER_PICK will be called when the user selects something by single clicking or area selecting with "Area Select Visible Geometry Only" enabled. The framebuffer consists of 2 ivec2 attachments. The first one should have the value of the ivec3 RE_UNIFORM_PICK_BASE_ID builtin uniform written to it, and the second, the ivec3 RE_UNIFORM_PICK_COMPONENT_ID. The base ID should not be changed by the hook, but you can alter the component ID. You don't need to use the component uniform solely, you can dynamically assign all or part of it in the shader. Note that this hook can be called multiple times with different pick components, passed in the DM_SceneHookData as pick_type. If you don't have that type of component, don't render anything. Once the pick render is done, () will be called with the pick records that were selected. This may be an empty list if nothing was selected in your hook. The pick buffer is only regneerated when the scene changes, so selectionResult() could be called many times without a corresponding hook render (though the hook render will always be called before it at least once).DM_HOOK_FRUSTUM_PICK will be called for an volume selection (area selection with "Area Select Visible Geometry Only" off). Unlike the framebuffer pick, nothing is rendered to a framebuffer. You can use a geometry shader and transform feedback to fetch the pick IDs, or your can simply compute what's in the frustum on the CPU. The frustum area is sent in DM_SceneHookData via pick_area. If lasso or paint is used, the mask is sent in pick_mask (an array of uint8 the size of pick_area.w()*pick_area.h() ). No () callback is provided for this method as the hook knows what is selected during the course of processing the picks.NOTE: For Houdini 20.0, some of the render passes are still rendering to OpenGL framebuffers as is Vulkan gradually integrated. The passes that cannot use Vulkan for rendering are:
There are several scene hook examples:
HDK_Sample::DM_BackgroundHook : Replaces the Houdini background with a checkered one. A good beginner example. (DM_BackgroundHook.C)HDK_Sample::DM_InfoHook: Prints the current SOP at the bottom of the viewport, demonstrating how to query details in the viewport and draw text. (DM_InfoHook.C)HDK_Sample::DM_SceneBoundsHook: Draws a bounding box around all objects in the scene. This demonstrates how to iterate over all displayed items in the viewprot and draw in 3D. It also shows how to restrict the hook from the UV viewport. (HDK_SceneBoundsHook.C)HDK_Sample::DM_LightBloomHook: Draws a simple glow around bright objects, illustrating how to query the beauty framebuffer and use it to add an additional effect. (DM_LightBloomHook.C)HDK_Sample::DM_ObjectPathHook: Draws a path with the up vectors at each frame for the current object, if animated. Demonstrates how to query objects directly and draw more complex guides in the 3D viewport. (DM_ObjectPathHook.C)HDK_Sample::DM_OverdrawHook: A sample showing how to register a hook in multiple passes, sharing data between passes. This hook measures the total samples drawn in the viewport and determines the overdraw percentage, based on how many samples were rejected by depth testing. (DM_OverdrawHook.C)A GUI_PrimitiveHook's only reponsibility is to create a GR_Primitive from given criteria using the createPrimitive() method, or to produce a new GT_Primitive from filterPrimitive(). This method is only called if the primitive's type ID matches the one currently be processed in the GU_Detail. A hook can be a GR_Primitive creator, or a GT_Primitive filter (via GUI_HOOK_FLAG_PRIM_FILTER), but never both. This section deals with hooks that override createPrimitive() to create new GR_Primitive types.
The hook can simply handle all primitives passed to it, which are guarenteed to be of the type it was registered with, or do a more detailed inspection of the primitive's attributes or values.
Both a GT and GEO primitive are passed, though the GEO primitive will be NULL if this hook is defined for a GT primitive type. The 'info' and 'cache_name' parameters are needed by the base GR_Primitive class constructor, so they are generally passed straight though the custom GR_Primitive's constructor. The processed parameter must not be GR_NOT_PROCESSED if a new GR_Primitive is returned, and it can take the following values:
The non-exclusive case often requires that the GUI_PrimitiveHook is installed with a higher priority than other custom hooks for the same type, especially if they return GR_PROCESSED.
Once a GR_Primitive is created, it gains some autonomy in maintaining itself. In order to provide better performance, the viewport attempts to reuse existing GR primitives whenever possible. If a GU_Detail is changed, the next update for the detail will first call acceptPrimitive() for each primitive that was previously generated. In this case, the GT or GEO type passed to acceptPrimitive() may not match the GR_Primitive's expected type:
GR_Primitives are deleted when no longer needed. This can occur if:
Once a GR_Primitive has been created for a primitive, or group of primitives, it will generally be updated and rendered. A GR_Primitive can be persistent over multiple GU_Detail changes, so information can be cached within the GR_Primitive itself or in the GL cache. There are two main phases of a GR_Primitive - updating and rendering.
A GR_Primitive is updated primarily through its update() method. It is responsible for creating all data required for the render methods. Textures, buffers, and other GL objects should all be created in this method.
update() is called much less often than render, so it is recommended that any heavy computation is done in update() rather than the render methods. update() is called when:
The reason for the update is stated in the bitfield p.reason. Multiple reasons may be given.
In addition to update(), there is a virtual viewUpdate() method which is called if only the view frustum has changed and the primitive requested view change updates.
Rendering is performed in render(). The basic render method is:
Each primitive can be rendered in a variety of ways, not all of which need to be supported by a custom primitive. The render modes are:
Modes when you don't intend to support should immediately return from render(). Ignoring some modes, like Hidden Line, will cause your geometry to disappear when a user selects "Hidden Line" mode, so in some cases it is better to substitute a close render mode (like Wireframe). Other modes, like Matte or Depth Linear, will cause the object not to highlight when located or participate in shadow maps.
There are also variations for some modes, usually shaded ones, passed in the GR_RenderFlags parameter:
render() is frequently called more often than update(), such as when tumbling the view, so it is recommended that this method be as lightweight as possible.
A hook must be coded for Vulkan if Vulkan is the current renderer, and a GL4 renderer must be used if the rendering is OpenGL. For GUI_PrimitiveHook, return a mask of all the renderers the hook supports. For DM_SceneHook, return true if the renderer passed to supportsRenderer() is supported. Your hook can support both; instead of passing an RE_Render pointer to the render and update methods, an RE_RenderContext is passed instead. If Vulkan is active, its isVulkan() will return true. If your hook doesn't support Vulkan, return immediately if this is true. Similarly, if your doesn't support OpenGL, return if it is false. An RE_Render (GL) or an RV_Render (Vulkan) can be extracted from the RE_RenderContext.
There are also several ways to do OpenGL rendering within Houdini. The first method is to use OpenGL or Vulkan directly. The second uses higher-level RE or RV objects such as RE_Shader, RE_Geometry, and RE_VertexArray. These gain the benefits of the Houdini GL cache, GL extension abstractions, and simpler interfaces. The third way is through GR classes designed to render various classes of objects in the viewport (GR_PolySurfaceGL3, GR_VolumeGL3, GR_PointsGL3, GR_PolySurfaceVK). These classes know all about picking, selection, instancing, and special draw modes, like hidden line, ghosting and shadowmap rendering.
All three methods have their advantages, and generally trade off flexibilty for quicker development when moving from raw GL/Vulkan, to RE/RV, to GR.
The following pages cover these rendering topics in more detail.
In addition to the normal GUI_RenderHook, there is a primitive filter hook. It is registered with the GUI_HOOK_FLAG_PRIM_FILTER flag (and only that flag):
When this type of hook is active, it creates a new GT_Primitive for the input GT or GEO primitive:
The new GT primitive may be of the same type as the input primitive, or it may be a completely different type, such as converting a polygon mesh into a point cloud.
A filter hook should always set 'processed' to GR_PROCESSED if it always or might affect its primitive, such as if it is conditionally applied using display option. This ensures that the refinement process knows that it may be conditionally applied. Returning a NULL GT_PrimitiveHandle from a filter will cause it to be ignored even if GR_PROCESSED is returned.
Registering a primitive display option for a filter handle requires the 'refine_requred' flag to be set:
This will trigger a geometry refine when the option is toggled so that the filterPrimitive() method is called again. Only filter hooks require this; primitive creation hooks should not set it.
The filter effect can then be toggled on or off (as taken from the GUI_PolygonNormalShade HDK sample):
The only restriction for a filter hook is that it can only return a single GT_Primitive. It cannot return a collection of GT_Primitives.
1.8.6