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


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103
							<!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> Files</H1><P>The file API handles all saving and loading of data in the framework using Buffer objects.
This makes sure that anything that can be saved to a file can be embedded into the application's binary, encrypted, compressed, sent over a network, merged into an archive with other assets, or whatever you want to do with it.

</P><P>
</P><IMG SRC="Images/Border.png"><P>
</P><H2> Paths and current directory</H2><P>All file operations that send a file path to the operating system have the file_optimizePath function cleaning up the path for you, so it might accept a path that is actually invalid on the system if entered outside of the framework.
Before saving a path to a file, make sure to apply file_optimizePath on the path yourself to get the absolute path that is actually used by the operating system based on the current path.
file_optimizePath will remove following ./, collapse folder/../, reduce redundant separators and replace incorrect separators with the local system's standard, so that you can write a hardcoded relative path that works on both Windows and Posix systems.
It can however not add or remove drive letters, so relative paths are portable paths.
file_optimizePath can also be used to reformat slashes for another system by specifying the platform using the pathSyntax argument.

</P><P>
On Windows, you can have a path beginning with:

</P><P>
* A drive letter, such as C:\

</P><P>
* An implicit current drive root, written as \

</P><P>
* A relative path beginning from the current directory, such as folder\files\document.txt

</P><P>
On Posix, you can have a path beginning with:

</P><P>
* The logical system root on top of all physical drives and partitions, written as /

</P><P>
* The current user's home directory using ~ to replace /home/username

</P><P>
* A relative path beginning from the current directory, such as folder/files/document.txt
</P><IMG SRC="Images/Border.png"><P>
</P><H2> Best practice</H2><P>Store paths in relative form when you want things to work across different computers, but remember that relative paths are usually relative to the location from which the application was called, which is usually the desktop from where the shortcut started the program.
If your application worked fine while building it from the same folder, but crashes from not finding resources when called from a shortcut, you need to handle your current path somehow.

</P><P>
Use absolute paths when you are working on one computer but often needs to access a file from different locations.

</P><P>
Use relative paths when you either want to process files specified by the user, or convert paths into absolute form using a theoretical path before use.

</P><P>
Use file_setCurrentPath(file_getApplicationFolder()); on start-up if you often forget to convert your relative paths into absolute paths.
Changing the current path is bad practice because it prevents you from using paths relative to the caller origin, but it is also the easiest way to handle all paths relative to the application if you really don't need to access files from the caller's path.
A compromise is to convert any paths from command line arguments into absolute paths before overwriting the current path with the application path.
</P><IMG SRC="Images/Border.png"><P>
</P><H2> Saving and loading</H2><P>
</P><P>
file_loadBuffer and file_saveBuffer are the main functions for saving and loading buffers of binary data.

</P><P>
Both the string API and the image API calls these for the functions saving and loading to string, and offer alternatives directly against the Buffer objects.
string_save also has string_saveToMemory for saving the encoded string with byte order marks and unicode code points into a Buffer.
string_load also has string_loadFromMemory for loading a text document as if the Buffer was a file.
image_save also has image_encode to store a PNG, Jpeg, Targa or BMP image into a Buffer.
image_load_RgbaU8 also has image_decode_RgbaU8 to decompress the image back from the buffer.

</P><P>
</P><IMG SRC="Images/Border.png"><P>
</P><H2> An easier alternative to std::filesystem</H2><P>
</P><P>
* Instead of exposing each platform's native string encoding, DSR's file API has one unified UTF-32 string format for cross-platform Unicode support in filenames.

</P><P>
* Instead of demanding the use of C++17, the static library calls the system's C API directly when needed to support C++14.

</P><P>
* Instead of using dangerous iterators (which are unprotected raw pointers) to seek through a folder, file_getFolderContent will give safe lambda callbacks for each entry.

</P><P>
Maybe std::filesystem will live longer than the Posix standard, but in that case it would be relatively easy to wrap this API on top of STD, because they have very similar functionality.
</P><IMG SRC="Images/Border.png"><P>
</P>
</BODY> </HTML>