cpp
/
3DSoftwareRenderer-DFSPR
mirror of https://github.com/Dawoodoz/DFPSR.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125
							<!DOCTYPE html> <HTML lang=en> <HEAD> <STYLE>
body { background-color: #EEFFEE;  font-size: 1.0rem; font-family: Arial; max-width: 60rem;
      color: #000000; margin: 0px;
      padding-left:  0px; padding-right:  0px; padding-top:  0px; padding-bottom:  0px; }
H1 {  padding-left: 10px; padding-right:  0px; padding-top: 10px; padding-bottom: 10px; font-size: 1.4rem; }
H2 {  padding-left: 10px; padding-right:  0px; padding-top: 10px; padding-bottom:  0px; font-size: 1.2rem; }
blockquote {
  tab-size: 3rem;
  color: #88FF88; background: #000000;
  font-size: 0.95rem; font-family: monospace;
  padding-left: 5px; padding-right: 5px;
  padding-top: 5px; padding-bottom: 5px;
}
P {   padding-left: 20px; padding-right:  0px; padding-top:  0px; padding-bottom:  0px; }
IMG { padding-left:  0px; padding-right:  0px; padding-top:  2px; padding-bottom:  0px;
      max-width: 100%; }
A { display: inline; border-radius: 4px;
    font-size: 1.0rem; font-family: Arial; color: #000044; text-decoration: none;
    padding-left: 4px; padding-right: 4px; padding-top: 4px; padding-bottom: 4px; }
A:hover { color: #FFFF00; background: #000044; }
A:active { color: #FFFFFF; background: #444444; }
</STYLE> </HEAD> <BODY>
<IMG SRC="Images/Title.png" ALT="Images/Title.png">
<P>
<A href="Manual.html">Back to main page</A>
</P><P>
</P><H1> Troubleshooting</H1><P>
</P><P>
<IMG SRC="Images/SmallDot.png">
If your program crashes with segmentation faults, start by replacing pointers with SafePointer and building the program in debug mode.

</P><P>
In the Builder build system, debug mode is activated by writing 'Debug' in the *.DsrProj project file, which declares the Debug variable and assigns it to one.

</P><P>
For other build systems, give -DDEBUG to the compiler to define the DEBUG macro.
Make sure that the release flag -DNDEBUG is not also active.

</P><P>
Then memory.h will enable the SAFE_POINTER_CHECKS macro from detecting debug mode.
Then SafePointer.h will store the permitted region in each SafePointer and perform bound checks when data is accessed using SafePointer.

</P><P>
</P><IMG SRC="Images/Border.png"><P>
</P><H2> Getting random memory crashes.</H2><P>
</P><P>
<IMG SRC="Images/SmallDot.png">
If your program is getting random memory corruption despite using SafePointer and debug mode, continue by enabling the EXTRA_SAFE_POINTER_CHECKS macro.

</P><P>
In the Builder build system, extra safe memory checks can be enabled for debug mode by writing 'CompilerFlag "-DEXTRA_SAFE_POINTER_CHECKS"' in the *.DsrProj project file.
EXTRA_SAFE_POINTER_CHECKS can also be defined as a macro in settings.h or by giving -DEXTRA_SAFE_POINTER_CHECKS to a different build system.

</P><P>
Then SafePointer will check that the allocation has not been replaced by another allocation in heap.cpp.
SafePointer will also check that no thread is trying to access virtual stack memory allocated by another thread.

</P><P>
<IMG SRC="Images/SmallDot.png">
If your program does not crash but your image filters do not work as expected, create a debug window showing internal images or debug overlays with coordinates on top of the program's existing graphics.

</P><P>
<IMG SRC="Images/SmallDot.png">
Make sure that all your multi-threading can be turned off easily when finding the root cause.

</P><P>
<IMG SRC="Images/SmallDot.png">
Create a basic reference implementation without dangerous optimizations for every advanced feature.
Both for finding the cause of instability and being able to remove a feature without sending emergency patches in panic with more bugs.
Image filters are first written using lambdas returning the color of a pixel based on the pixel coordinate and exception-free pixel sampling.
Then one can make an optimized version using SafePointer and SIMD vectors.

</P><P>
</P><IMG SRC="Images/Border.png"><P>
</P><H2> Getting memory leaks.</H2><P>
</P><P>
In debug mode, terminating the program should print "All heap memory was freed without leaks.".
If it does not, you might have a memory leak for memory allocated by the framework in heap.cpp.
Due to the non-deterministic release order for global variables in C++, it is not possible to print a warning when there is a memory leak without redefining the _start function.

</P><P>
<IMG SRC="Images/SmallDot.png">
Avoid using manual memory management (malloc, free, new, delete...), use dsr::Handle for object handles.

</P><P>
<IMG SRC="Images/SmallDot.png">
Make sure that no reference counted object can create a cycle of reference counted pointers back to itself, because then none of them would be unused according to reference counting.

</P><P>
<IMG SRC="Images/SmallDot.png">
Use the dsr::Buffer object instead of C allocation calls, to let it automatically free your memory when nobody keeps the reference counted handle.
You can then work on its memory using SafePointer, which provides bound checks in debug mode, but must be kept close to the buffer's reference counted handle to keep the data it points to alive.
<A href="Buffers.html">Read about the Buffer API</A>
</P><P>
<IMG SRC="Images/SmallDot.png">
Remember that a reference in C++ is a pointer under the C++ syntax, which can also cause crashes if taken from a location in memory that may be freed during the call.
If you passed "const SomeClass &object" from "List<SomeClass>" to a function that can reallocate the list that the object is stored in, this can cause a crash by referring to a memory location that got replaced by the list.
If you instead pass "SomeClass object" from "List<SomeClass>", the object will be copied in the call instead of referring to freed memory.
Returning a reference to a stack allocated variable, can also cause crashes with references.

</P><P>
</P><IMG SRC="Images/Border.png"><P>
</P><H2> The application crashes, but the debugger does not detect it.</H2><P>
</P><P>
Use a debugger directly on the application with debug symbols enabled when compiling.
Connecting Valgrind to the script used to run your application will catch memory leaks, but not invalid memory access.
Without debug symbols, you can see which method crashed, but not the line.
</P><IMG SRC="Images/Border.png"><P>

</P><P>
</P><H2> Getting linker errors when creating a new project without a window.</H2><P>
</P><P>
Linking to a window manager without using it may cause linker errors because the renderer library makes a call to outside of the library.
If you have linked with guiAPI.cpp, you need to import DFPSR.DsrHead in your *.DsrProj build script.
If the Graphics variable is default assigned to 1 before DFPSR.DsrHead is imported, a window manager will be selected based on which system you are compiling for.
If the Graphics variable did not exist, was accidentally placed after the DFPSR.DsrHead import, or you assigned it to 0, then NoWindow.cpp will be used as a stub implementation to throw an exception if someone tries to actually create a window.
</P><IMG SRC="Images/Border.png"><P>

</P><P>
</P><H2> Getting linker errors with duplicate symbols when building on an operating system with a case insensitive file system.</H2><P>
</P><P>
The Builder build system needs consistent paths to files, so if your C++ source code includes from "dfpsr" but your project imports from "DFPSR", the different paths to the same files will be treated as different files and linked twice.
</P><IMG SRC="Images/Border.png"><P>
</P>
</BODY> </HTML>