[CriFs] Native API wrapper

Description of the sample

Overview

This sample uses a class that wraps the native API of the CRI File System (FileMajik PRO runtime library).

Operations

• Step 1: Bind CPK Files
  
  • Bind CPK File (Local) button
    Binds a local CPK file.
    
    
• Step 2: Load File
  
  • Load Image File button
    Loads an image file from any CPK file.
    
    
  • Load Text File button
    Load a text bundle file from any CPK file.
    
    
• Stop Loading button
  Stops loading.
  
  
• Reset button
  Resets the setting.
  
  

Scene information

Middleware	FileMajik PRO (CRI File System)
Sample	Basic samples
Location	/CRIWARE/SDK/unity/samples/UnityProject/Assets/Scenes/crifilesystem/basic/
Scene file	Scene_06_NativeApi.unity

Description of the program

[Overview of the program]

This sample uses a class that wraps the native API of the CRI File System.
It monitors the status in the Update function without using the yield statement.
It loads the "criware.png" image file and "sample_text.txt" text file from the "sample.cpk" pack file.
A "binder" is a virtual drive. When you use the BindCpk function to bind a packed file (CPK file) to a binder, you can load a file from the CPK file.

Multiple packed files can be bound. The BindCpk function returns binding IDs. Binding multiple files is called "multi-binding".
You can load a file by specifying the binder and the file name in the loader.

1. Bind "sample.cpk" to the CriFsBinder binder (using the BindCpk function).
   
2. Check that the binding has completed in the Update function. (using the GetStatus function)
   
3. Specify a binder and a file name ("criware.png" and "CharMw.unity3d"), and instruct the loader to start loading. (using the Load function)
   
4. Check that the loader has finished loading in the Update function. (using the GetStatus function)
   
5. To cancel loading, execute the Stop function of the loader.
   
   

== Tips ==

• To load multiple files faster, use multiple loaders simultaneously.
  
• By binding a CPK file, you can obtain file sizes quickly. When you try to obtain the size of an unpacked file, the process is blocking.
  

[Description of the program]

(1) Creating a binder and loaders

binder = new CriFsBinder();   /*  Binder            */
loader1 = new CriFsLoader();  /*  For an image file          */
loader2 = new CriFsLoader();  /*  For a text file  */

Create a binder and a couple of loaders when the application is started.
This sample creates these objects by using their constructors directly.
Simultaneous loading using multiple loaders in the background is faster than loading multiple files successively with a single loader.

(2) Registering a packed file (CPK file) with a binder

bind_id = binder.BindCpk(null, path);

Bind a CPK file to a binder.
The BindCpk function starts loading the directory information of the CPK file.
You can bind multiple CPK files to one binder. The BindCpk function returns a binding ID, which identifies the CPK files.

if ( CriFsBinder.GetStatus(bind_id) == CriFsBinder.Status.Complete ) {
  bind_stat = BindStatus.Complete;
}

Check whether binding has finished successfully by specifying the binding ID in the GetStatus function.

(3) Loading a file

int file_size = (int)binder.GetFileSize(path);
buffer1  = new byte[file_size];
loader1.Load(binder, path, 0, file_size, buffer1);

Obtain the file size by specifying the file name in the binder. If the CPK is bound, you can obtain the file size immediately from the directory information that is already in memory.
Even if nothing is bound in the binder, you can obtain the size of a local file or network file, but the GetFileSize function is blocking. This can be avoided by using a CPK file.
When the Load function is executed, file loading is started.
The file must be specified by giving the binder and the file name. The third argument is the offset in the file. By specifying this, you can start loading the file from any position.

if ( loader1.GetStatus() == CriFsLoader.Status.Complete ) {
    this.texture = new Texture2D(0, 0);
    this.texture.LoadImage(buffer1);
    loader1.Stop();
}

Use the GetStatus function to check whether the loading is finished or not.
If the status returned is "Complete", the loading is finished.
If a loading error occurs, the "Error" status is returned.
When the loading is complete, buffer1 contains the data.
(4) Stop loading a file

this.loader1.Stop();
this.loader2.Stop();

By executing the Stop function, the status changes to "Stop".
You can cancel loading. This can be convenient for the users.

(5) Releasing resources

this.loader1.Dispose();
this.loader2.Dispose();
this.binder.Dispose();

When you are closing the scene or destroying the loader and the binder, execute the Dispose function.
The resources used by the native API are released.