<HTML>
	<HEAD>
		<TITLE>Reference manual for David Piuva's graphics engine</TITLE>
	</HEAD>
	<BODY>
		<link rel="stylesheet" type="text/css" href="PageStyle.css">
		<A href="../Manual.html">Back to main page</A>
<P>		<b>Debug guide</b>
<P>		If a model that you need to debug is generated in the game, save the result to a file using Model_SaveToFile_InSB and open it in the model editor.
<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> The application is crashing when closing the main window!
<P>	<IMG SRC="Images/Solution.png"> Terminate the application when the window class is unloading. Both rendering and the sound engine is using the window and will get a nasty surprise if it suddenly does not exist.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> The application is crashing when giving multiple calls at once to the engine!
<P>	<IMG SRC="Images/Solution.png"> Only make one call at a time and treat the whole engine as shared variable.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> The application is crashing without closing the window or using multiple threads!
<P>	<IMG SRC="Images/Solution.png"> Download and use the latest version of the engine or send a bug report about the error. Send a link to a small project with sourcecode that recreate the error.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> The image is black!
<P>	<IMG SRC="Images/Solution.png"> If you have disabled automatic swap chain using Engine_SetAutomaticSwapChain, you must call Engine_UpdateSwapChain to show the final draw surface to the user.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> My shader animation is not moving!
<P>	<IMG SRC="Images/Solution.png"> Use Shader_SetGlobalTime before each render to give the current time to all your shaders.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> I can't change the shader for one of my models!
<P>	<IMG SRC="Images/Solution.png"> Note that a model can have multiple parts with different sets of shaders.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> Alpha filtering is not working!
<P>	<IMG SRC="Images/Solution.png"> Make sure that your texture's alpha channel was loaded by using an HLSL shader that show alpha as grayscale.
<P>	<IMG SRC="Images/Solution.png"> Make sure that your shader is returning the alpha channel to the render target by using a post effect that show alpha as grayscale.
<P>	<IMG SRC="Images/Solution.png"> Make sure that the model is using alpha filter by opening it in the model editor.
<P>	<IMG SRC="Images/Solution.png"> Make sure that you are rendering the same shader channel that the shader is assigned to.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> My soft particles are not working at all!
<P>	<IMG SRC="Images/Solution.png"> See "Alpha filtering is not working" since soft particles only work with filters.
<P>	<IMG SRC="Images/Solution.png"> Make sure that the draw surface that the scene is rendered to is using 2 depth buffers.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> My soft particles look flat when intersecting solid geometry!
<P>	<IMG SRC="Images/Solution.png"> Use this:
<P>	<FONT COLOR="#00BB00">// This value represent the solid background's camera space Z depth and is generated by sampling the depth buffer copy and converting from ZW to linear using the current camera's projection matrix.</FONT>
<P>	float DepthBufferLinear = CameraToImage._43 / (tex_depthBufferCopy.Sample( samConstant, input.Pos.xy / Dimensions ) - CameraToImage._33);
<P>	<FONT COLOR="#00BB00">// This value can be multiplied with the final alpha.</FONT>
<P>	float CloseToBackgroundFading = saturate(DepthBufferLinear - input.Pos_CameraSpace.z);

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> My soft particles look flat when intersecting the camera!
<P>	<IMG SRC="Images/Solution.png"> Use this:
<P>	<FONT COLOR="#00BB00">// This value can be multiplied with the final alpha so that it fade away softly when being close to the near clip plane.</FONT>
<P>	float CloseToCameraFading = saturate(input.Pos_CameraSpace.z - NearClipPlane);

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> Alpha clipping is not working!
<P>	<IMG SRC="Images/Solution.png"> Make sure that your texture's alpha channel was loaded by using an HLSL shader that show alpha as grayscale.
<P>	<IMG SRC="Images/Solution.png"> Clip the pixel when alpha is below 0.5 for a smooth edge.
<P>	<IMG SRC="Images/Solution.png"> Make sure that you are rendering the same shader channel that the shader is assigned to.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> My item look strange!
<P>	<IMG SRC="Images/Solution.png"> Start by reading your shader code and compare it with working shaders.
<P>	<IMG SRC="Images/Solution.png"> Return a simple color from your shader to see that you are editing the same shader that you see.
<P>	<IMG SRC="Images/Solution.png"> Return one vertex property at a time from the shader to see that they are working.
<P>	<IMG SRC="Images/Solution.png"> Use the editor to make sure that the vertex color and texture coordinates are not 0.
<P>	<IMG SRC="Images/Solution.png"> Use the editor to generate normals if your shader is using them.
<P>	<IMG SRC="Images/Solution.png"> Make sure that all texture channels sampled by the material shader has an image assigned.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> My item is not visible!
<P>	<IMG SRC="Images/Solution.png"> Make sure that the instance's axis system is well scaled.
<P>	<IMG SRC="Images/Solution.png"> Make sure that the instance is visible in the shader channel that your camera is rendering. Use Instance_GetVisibility and Instance_SetVisibility.
<P>	<IMG SRC="Images/Solution.png"> Make sure that the model is using the correct culling method. Use the model editor to choose a method. Try using no culling to make sure that you have found the error before choosing the right type.
<P>	<IMG SRC="Images/Solution.png"> Make sure that the model has visible parts in all detail levels. Try viewing the model in low, medium and high detail level in the model editor.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> My item is not casting shadows!
<P>	<IMG SRC="Images/Solution.png"> Make sure that the light source is shadowcasting. The constructor method should include "_Shadowcasting" and not "_Shadowless"
<P>	<IMG SRC="Images/Solution.png"> Make sure that the light source has shadow transparency set to 0. Use LightSource_GetShadowTransparency and LightSource_SetShadowTransparency.
<P>	<IMG SRC="Images/Solution.png"> Make sure that the depth atlas is not out of space. Use Debug_WasDepthAtlasAllocationDenied before calling LightSource_ClearShadows.
<P>	<IMG SRC="Images/Solution.png"> Make sure that the instance is casting shadows. Use Instance_GetVisibility and Instance_SetVisibility with shader channel 1.
<P>	<IMG SRC="Images/Solution.png"> Make sure that all parts in the model have a shader in channel 1 (depth only). Use the model editor.
<P>	<IMG SRC="Images/Solution.png"> Make sure that the depth only shader is not clipping everything from a bad vertex color or bad HLSL code. Use the model editor to see what shaders are assigned to channel 1.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> My shadowcasting light source is casting weird shadows and I use one camera/render call!
<P>	<IMG SRC="Images/Solution.png"> Call LightSource_ClearShadows before each render to remove the first thing that the light source saw.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> My shadowcasting light source is casting weird shadows and I use multiple cameras/render calls!
<P>	<IMG SRC="Images/Solution.png"> Call LightSource_ClearShadows before the frame's first render so that the first render call that show the light source will render the depth map and the next render calls will reuse that map. This looks as if the light source is projecting an image.
<P>	<IMG SRC="Images/Solution.png"> Make sure that light source is not moved in any way between the render calls. This bug took days to find in the forest example because it looks like an internal error.
<P>	<IMG SRC="Images/Solution.png"> Make sure that no shadowcasting instance is moved between the render calls.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> My shadowcasting light sources take too much rendering time and I use multiple cameras/render calls!
<P>	<IMG SRC="Images/Solution.png"> Only call LightSource_ClearShadows before the frame's first render so that the next render calls will reuse that depth map that was created the first time the light source was visible.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> I can't use my draw surface as a dynamic texture!
<P>	<IMG SRC="Images/Solution.png"> Make sure that the part's instance override is listening to the same channel that you assigned the draw surface to using Instance_SetTextureOverride.
<P>	<IMG SRC="Images/Solution.png"> Make sure that the used shader is sampling the texture channel that you are overriding.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png"> I have generated a sound but I can't hear it.
<P>	<IMG SRC="Images/Solution.png"> Call Sound_Buffer_Editable_Update before playing it.
<P>	<IMG SRC="Images/Solution.png"> Try saving the current content to a wave file and opening the result in a sound editor to see if it is a sound or a flat line.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png">The visual instance is not following the rigid body when I place the instance at the rigid body manually.
<P>	<IMG SRC="Images/Solution.png"> Call Instance_PlaceAtRigidBody or Instance_PlaceAtRigidBody_Interpolated with the instance and rigid body before each render.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png">The visual instance is not following the rigid body when I let the instance follow the rigid body automatically.
<P>	<IMG SRC="Images/Solution.png"> Make sure that you have connected the instance to the rigid body using Instance_FollowRigidBody
<P>	<IMG SRC="Images/Solution.png"> Call Physics_LetInstancesFollowRigidBodies or Physics_LetInstancesFollowRigidBodies_Interpolated before each render.

<P>	<IMG SRC="Images/Border.png">

<P>	<IMG SRC="Images/Problem.png">The visual instance is not scaled like the rigid body's shape.
<P>	<IMG SRC="Images/Solution.png"> Make sure that the UseLocalScaling flag is true in the method that you use to synchronize the instance with the rigid body.
<P>	<IMG SRC="Images/Solution.png"> Make sure that the shape is scaled using the local scaling property and not just using different dimensions when creating the shape. You should think of the shape's dimensions as object space and local scaling as the conversion to world space.

<P>	<IMG SRC="Images/Border.png">
	</BODY>
</HTML>