 | |
Sharp | |
SharpEngineSceneView is a control that can show a 3D scene that is defined by the Scene and SceneView objects.
See remarks for more info.
Inheritance HierarchyNamespace: Ab4d.SharpEngine.WinUI
Assembly: Ab4d.SharpEngine.WinUI (in Ab4d.SharpEngine.WinUI.dll) Version: 2.0.8956+4c7684e186ca1be74e7a284fbe739d9a1b843d3c
SyntaxC#
public class SharpEngineSceneView : ContentControl, ISharpEngineSceneView, IComponentBase
The SharpEngineSceneView type exposes the following members.
Constructors| Name | Description | |
|---|---|---|
 | SharpEngineSceneView | Creates the SharpEngineSceneView object (PresentationType is set to SharedTexture). This also creates the Scene and SceneView objects. The VulkanDevice is automatically created when this control is loaded. To manually create or set the VulkanDevice, call the Initialize method. |
| SharpEngineSceneView(PresentationTypes) | Creates the SharpEngineSceneView object and sets the PresentationType property. This also creates the Scene and SceneView objects. The VulkanDevice is automatically created when this control is loaded. To manually create or set the VulkanDevice, call the Initialize method. |
Properties| Name | Description | |
|---|---|---|
 | BackgroundColor | Gets or sets a background color for SharpEngineSceneView. Default color is White. Note that when using SharedTexture as PresentationType and when UseSwapChainPanelForSharedTexture is true (by default), then Transparent color cannot be used as BackgroundColor. |
| CreateOptions | Gets the EngineCreateOptions that were used to create the VulkanInstance and VulkanDevice. |
| DpiScaleX | Gets or sets a float that represents a DPI scale factor in X direction: 1 means 96 DPI, 1.5 means 144 DPI, etc. This value is used in line and pixel rendering and scales the line thickness or size of pixels. |
| DpiScaleY | Gets or sets a float that represents a DPI scale factor in Y direction: 1 means 96 DPI, 1.5 means 144 DPI, etc. This value is used in line and pixel rendering and scales the line thickness or size of pixels. |
| GpuDevice | Gets the graphics device object (VulkanDevice). |
| Id | Gets a unique id of this resource |
| IsDisposed | Gets a Boolean that specifies if this resource has been disposed. |
| IsDisposing | Gets a Boolean that specifies if this resource is currently being disposed (the current code is executing inside Dispose method). |
| IsVisible | |
| PreferredMultiSampleCount | PreferredMultiSampleCount can be set before the SceneView is initialized and defines the multi-sampling count (MSAA) that will be used if supported by the device. After initializing the SceneView, the actually used multi-sampling count is set to the UsedMultiSampleCount property. |
| PresentationType | Presentation type defines how the rendered 3D scene will be presented to the platform. Default value is SharedTexture. |
| Scene | Gets the Scene that defines the 3D objects. |
| SceneView | Gets the SceneView that renders the Scene to this control. |
| StopRenderingWhenHidden | Gets or sets a Boolean that specifies if rendering is stopped when this control is hidden (IsVisible goes to false). Default value is true. |
| UseInverseDpiScaleOnSwapChainPanel | When true, then the scale of the SwapChainPanel is set so that the SwapChainPanel correctly shows the content of the SceneView (otherwise only the top-left part of the whole scene is shown - the size depends on the screen's DPI settings). This is required to fix a bug in a SwapChainPanel. Default value is true. |
| UseSwapChainPanelForSharedTexture | When true (by default) then WinUI's SwapChainPanel is used for SharedTexturePresentationType. When false, then WinUI's SurfaceImageSource is used. See Remarks for more info. |
| WaitForVSync | Gets or sets a Boolean that specifies if the SceneView is waiting for a v-sync provided by the surface. This property is used only when OverlayTexture is used as a PresentationType. |
Methods| Name | Description | |
|---|---|---|
 | ArrangeOverride | |
| BeginSurfaceImageDraw | |
| Dispose | Disposes all resources that were created by this SharpEngineSceneView. |
| Dispose(Boolean) | |
| EndSurfaceImageDraw | |
| Finalize | Destructor |
| Initialize | Initialize method initializes the engine by using the CreateOptions from this SharpEngineSceneView. |
| Initialize(ActionEngineCreateOptions) | Initialize method initializes the engine by using EngineCreateOptions that are defined by the provided configureAction. |
| Initialize(EngineCreateOptions) | Initialize method initializes the engine by using the specified EngineCreateOptions. |
| Initialize(VulkanDevice) | Initialize method initializes the engine by using the specified VulkanDevice object. |
| IsDesignTime | Returns if the control is running in design time. |
 | IsPresentationTypePossible | Returns true when the specified presentationType may be supported by this SharpEngineSceneView control. To check if the presentationType is possible on the current or specific GpuDevice call the IsPresentationTypeSupported(PresentationTypes) or IsPresentationTypeSupported(PresentationTypes, String) or IsPresentationTypeSupported(PresentationTypes, VulkanDevice, String) methods. |
| IsPresentationTypeSupported(PresentationTypes) | Returns true when the specified presentationType is supported on the current GpuDevice. This method must not be called before the GpuDevice is created (before SharpEngineSceneView is initialized). |
| IsPresentationTypeSupported(PresentationTypes, String) | Returns true when the specified presentationType is supported on the current GpuDevice. When presentation type is not supported, a string with additional information is set to the additionalInfo parameter. This method must not be called before the GpuDevice is created (before SharpEngineSceneView is initialized). |
| IsPresentationTypeSupported(PresentationTypes, VulkanDevice, String) | Returns true when the specified presentationType is supported on the specified GpuDevice. When presentation type is not supported, a string with additional information is set to the additionalInfo parameter. |
| MeasureOverride | |
| OnApplyTemplate | |
| OnDisposed | OnDisposed |
| OnDisposing | OnDisposing |
| OnGpuDeviceCreated | OnGpuDeviceCreated |
| OnGpuDeviceCreationFailed | OnGpuDeviceCreationFailed |
| OnPresentationTypeChanged | OnPresentationTypeChanged |
| OnSceneRendered | OnSceneRendered |
| OnSceneUpdating | OnSceneUpdating |
| OnSceneViewInitialized | OnSceneViewInitialized |
| OnViewSizeChanged | OnViewSizeChanged |
| RenderScene | RenderScene rendered the scene. If forceRender is false then the scene is rendered only if there are any changes in the scene nodes. If forceUpdate is true then the RenderingQueues are always regenerated (otherwise RenderingQueues are regenerated only when this is required because of the changes). |
| RenderToBitmap(Boolean) | RenderToBitmap method renders the current scene to a new WinUI's WriteableBitmap. To reuse the WriteableBitmap, call the method that takes the WriteableBitmap by ref. See also the RenderToXXXX methods in the SceneView object. |
| RenderToBitmap(WriteableBitmap, Boolean) | RenderToBitmap method renders the current scene to the specified WinUI's WriteableBitmap. The size of the specified WriteableBitmap must be the same as the size of the SceneView or an exception will be thrown. See also the RenderToXXXX methods in the SceneView object. |
Events| Name | Description | |
|---|---|---|
 | Disposed | Occurs when this instance is fully disposed. The value of the parameter is the same the disposing parameter in the Dispose(bool) method. |
| Disposing | Occurs when this instance is starting to be disposed. The value of the parameter is the same the disposing parameter in the Dispose(bool) method. |
| GpuDeviceCreated | Called after the GpuDevice object was created. If device creation has failed, then GpuDeviceCreationFailed event is triggered. |
| GpuDeviceCreationFailed | Called when the device creation has failed. User can set the IsHandled property to true to prevent showing error text that is shown by SharpEngineSceneView. |
| PresentationTypeChanged | Called when the selected PresentationType is not supported and was changed to a fallback PresentationType. The event parameter may provide some additional information about the reason for change. |
| SceneRendered | Called after the scene has been rendered. |
| SceneUpdating | Called when the scene is being updated and before it is rendered. The event is called at the beginning of the RenderScene(Boolean, Boolean) method. This event can be used to update the animations. |
| SceneViewInitialized | Called after the SceneView object have been initialized (have a valid view size and the back buffers were created). |
| ViewSizeChanged | Called when the size of the rendering area is changed. The event is also called after the back buffers are initialized for the first time. |
Fields| Name | Description | |
|---|---|---|
 | RequiredDeviceExtensionNamesForSharedTexture | RequiredDeviceExtensionNames is a static List that contains the Vulkan device extension names that are required to use SharedTexture as presentation type. This list must be set before the VulkanDevice is created. |
 | writeableBitmap |
RemarksSharpEngineSceneView is a control that can show a 3D scene that is defined by the Scene and SceneView objects.
To add SceneNode objects to the Scene add them to the RootNode object. Lights can be added to the Lights collection. Camera can be set to the Camera property.
The SharpEngineSceneView automatically creates a GpuDevice when the control is loaded. To manually create or set the GpuDevice, call the Initialize method. GpuDeviceCreated and GpuDeviceCreationFailed events can be used to be notified when the GpuDevice is created or when the creation failed.
SharpEngineSceneView can use different presentation types that are defined by PresentationType property.
By default, the PresentationType is set to SharedTexture that can combine the rendered 3D scene with other UI controls and can preserve the data for the rendered texture on the graphics card.
When this mode is not supported on the UI framework or operating system, then WriteableBitmap is used. This presentation type is available on all UI frameworks and operating systems. It can still combine the 3D scene with other UI controls, but the rendered texture need to be copied to the main CPU memory to create a WritableBitmap.
The presentation type that provides the best performance is OverlayTexture. The drawback of this mode is that there the 3D scene is always rendered on top of other UI controls. This presentation type is not available on all platforms.
To check if other presentation type is supported, call IsPresentationTypeSupported(PresentationTypes) method. If selected presentation type is not supported, then WriteableBitmap will be used as fallback.
See Also