1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
4<meta http-equiv="Content-Style-Type" content="text/css" text="text/css">
5<title>TCL Features List</title>
6<link rel="stylesheet" href="../css/nitro.css">
7</head>
8<body>
9<h1>DSi Photo Database Library (TCL): Overview</h1>
10
11<h2>Introduction</h2>
12<p>The TCL library performs tasks such as loading JPEG images saved on NAND by the Nintendo DSi camera and writing JPEG images to paths that can be loaded by the DSi camera.</p>
13<p>Loading and writing JPEG images is based on information in management files, which are saved in memory separately from the image files.</p>
14<p>TCL manipulates files on NAND, so it can be used only with NAND applications.</p>
15
16<h2>Errors Related to FS Function Processes</h2>
17<p>With TCL, no special processes are performed for internally generated FS function errors. All error processes are left to the application. For any functions that use FS internally, error codes are returned by an argument, so use them to perform the necessary processes.</p>
18
19<h2>Loading Management Files and Errors</h2>
20<p>You must load a management file to use TCL functions.</p>
21<p>To handle errors when a management file failed to load: </p>
22<ul>
23<li>Output a message that prompts the user to start the DSi camera and reference the system memory on the DSi camera, and then quit subsequent processes.</li>
24<li>Recreate the management file.</li>
25</ul>
26<p>The risk of failure with loading the management file in system memory is low, and recovery can be performed with the DSi camera, so <b>there is basically no problem with the former error process</b>. In such cases, when application specifications are limited to loading (not writing) photos, it is possible to ignore several errors. For more information, see the <a href="TCL_LoadTable.html"><code>TCL_LoadTable</code></a> function.</p>
27<p>The following are the sequences used to attempt to recover management files in cases where gameplay reasons make recovery desirable. Even if the following processes are performed, management files might not be recovered, however.</p>
28
29<h2>Sequences to Attempt Recovering Management Files That Failed to Load</h2>
30<p>If a management file fails to load and you are recovering it, two error-handling sequences are available, depending on your application specifications. The first sequence is based on <I>next save</I> locations defined for images in the management file. If the save location is invalid, images are loaded but will not be written. If the management file fails to load for a different reason, both the loading and writing of images will fail.</p>
31<p>The error-handling sequences are explained in the following sections.</p>
32<h3>When Images Are Read-Only</h3>
33<p>This is a management file-loading sequence that includes an error-handling process only when loading images for application specifications. (See the manual for more information on the content of each function.)</p>
34<p><pre style="border:1px solid; black; padding:8px;">
35// Load the management file
36TCLResult result = TCL_LoadTable( &accessor ,
37                                  tableBuffer ,
38                                  tableBufferSize ,
39                                  workBuffer ,
40                                  workBufferSize ,
41                                  &fsResult );
42
43// The result of the load process
44switch ( result )
45{
46    case TCL_RESULT_SUCCESS: // Loading succeeded
47    case TCL_RESULT_ERROR_EXIST_OTHER_FILE: // A file already exists in the next save location
48    case TCL_RESULT_ERROR_ALREADY_MANAGED: // The next save location is already being managed
49        // The image loading process is performed, so nothing needs to be done
50                     :
51        break;
52    default:
53        // The image loading process is not being performed, so recreate the management file
54        result = TCL_CreateTable( &accessor ,
55                                  tableBuffer ,
56                                  tableBufferSize ,
57                                  workBuffer ,
58                                  workBufferSize ,
59                                  &fsResult );
60
61        if ( result == TCL_RESULT_SUCCESS )
62        {
63            // Images can be both loaded and written out
64                         :
65        }
66        else
67        {
68            // Images can neither be loaded nor written out
69                         :
70        }
71    }
72}
73</pre></p>
74<h3>When Images Are Read/Write</h3>
75<p>This is a management file-loading sequence that includes an error-handling process only when images can be loaded and written as per application specifications.</p>
76<p><pre style="border:1px solid; black; padding:8px;">
77// Load the management file
78TCLResult result = TCL_LoadTable( &accessor ,
79                                  tableBuffer ,
80                                  tableBufferSize ,
81                                  workBuffer ,
82                                  workBufferSize ,
83                                  &fsResult );
84
85// The result of the load process
86switch ( result )
87{
88    case TCL_RESULT_SUCCESS:// Loading was successful
89        // The image loading and writing processes are both performed, so nothing needs to be done
90                      :
91        break;
92
93    case TCL_RESULT_ERROR_EXIST_OTHER_FILE:// There is already a file in the destination for the next save
94    case TCL_RESULT_ERROR_ALREADY_MANAGED:// The destination for the next save is already managed.
95        // The writing process is not performed, so recalculate the next save location
96        result = TCL_RepairTable( &accessor , &fsResult );
97
98        if ( result == TCL_RESULT_SUCCESS )
99        {
100            // Images can be both loaded and written
101                          :
102        }
103        else
104        {
105            // The image-writing process cannot be performed, so recreate the management file
106            result = TCL_CreateTable( &accessor ,
107                                      tableBuffer ,
108                                      tableBufferSize ,
109                                      workBuffer ,
110                                      workBufferSize ,
111                                      &fsResult );
112
113            if ( result == TCL_RESULT_SUCCESS )
114            {
115                // Images can be both loaded and written out
116                              :
117            }
118            else
119            {
120                // Images can be neither loaded nor written out
121                              :
122            }
123        }
124        break;
125    default:
126        // The image loading process is not being performed, so recreate the management file
127        result = TCL_CreateTable( &accessor ,
128                                  tableBuffer ,
129                                  tableBufferSize ,
130                                  workBuffer ,
131                                  workBufferSize ,
132                                  &fsResult );
133
134        if ( result == TCL_RESULT_SUCCESS )
135        {
136            // Images can be both loaded and written out
137                         :
138        }
139        else
140        {
141            // Images can be neither loaded nor written out
142                         :
143        }
144    }
145}
146</pre></p>
147
148<h2>Example Message for Failure to Load a Management File</h2>
149<p>When the loading of a management file has failed, it might be necessary to display some form of message to indicate that photos cannot be worked with and that the management file should be recreated. Such cases are shown as an example based on DSi camera messages.</p>
150<p>However, these are only for your reference. Perform processes appropriate for the application.</p>
151<h3>When Loading a Management File Failed and Photos Cannot Be Worked With</h3>
152<p>No special message has been prepared for such cases on the DSi camera. (Handled as a fatal error.) For that reason, an example cannot be provided. It might be effective to provide a message that prompts the user to start the DSi camera and recover the file.</p>
153<h3>When Creating a Management File That Does Not Exist</h3>
154<p>When <code>TCL_RESULT_ERROR_NO_TABLE_FILE</code> is returned from the <a href="TCL_LoadTable.html"><code>TCL_LoadTable</code></a> function, it indicates that the management file does not exist. The following message is displayed in such situations.</p>
155<p><pre style="border:1px solid; black; padding:8px;">
156Creating the photo management file...
157</pre></p>
158<h3>When Recreating Because the Management File Could Not Be Loaded</h3>
159<p>The photo management file was broken when recreating the management file for other reasons. Recreate the photo management file. The following messages are displayed.</p>
160<p><pre style="border:1px solid; black; padding:8px;">
161The photo management file is corrupted.
162
163The photo management file will be regenerated.
164</pre></p>
165
166<h2>Writing Image Files</h2>
167<p>Image files cannot be written in the following situations.</p>
168<dl>
169<dd>There is insufficient NAND
170<dd>The maximum manageable number of photos is already being managed
171<dd>An addressable path does not exist for the save location
172</dl>
173<p>The <a href="TCL_CalcNumEnableToTakePictures.html"><code>TCL_CalcNumEnableToTakePictures</code></a> function calculates how many photos can be taken, based on the NAND capacity and the number of photos currently being managed. However, it does not determine whether it is possible to write to the specified path. Include logic similar to that shown in the following example when an image file is written.
174</p>
175
176<p><pre style="border:1px solid; black; padding:8px;">
177// Flags that maintain whether addressable path exists.
178// If TCL_RESULT_ERROR_NO_NEXT_INDEX is returned from TCL_RepairTable or TCL_CreateTable, there is not specifiable path, so the default value is FALSE.
179
180BOOL isEnableValidPath;
181
182// Where image is actually stored
183// Only take photo if 1 or more photos can be taken and there is a valid path
184if ( TCL_CalcNumEnableToTakePictures(,,) > 0 && isEnableValidPath != FALSE )
185{
186    result = TCL_EncodeAndWritePicture(,,);
187
188    // If, as a result of this save, there is no longer a valid path, hold this
189    if ( result == TCL_RESULT_ERROR_NO_NEXT_INDEX )
190    {
191        isEnableValidPath = FALSE;
192    }
193}
194</pre></p>
195<p>
196For more information, see the <CODE>tcl-2</CODE> demo.
197</p>
198
199<h2>JPEG Decoding Process</h2>
200<p>The <a href="TCL_DecodePicture.html"><code>TCL_DecodePicture</code></a> function to decode JPEG files is provided. This is a wrapper function for the <code>SSP_StartJpegDecoder</code> function, but because it performs the necessary internal error checks, decode using this function without calling the <code>SSP_StartJpegDecoder</code> function directly.</p>
201
202<h2>Differentiating Image Types</h2>
203<p>There are two types of images used with DSi cameras: photos and frames. Frames are used by the frame camera. Metadata information stored in the JPEG image defines its image type. TCL write operations must adhere to the specified image type.</p>
204<p>The management file stores image information independent of the metadata. Overwriting the management file, therefore, can lead to a mismatch between TCL data and image data.</p>
205<p>If this happens, unexpected results may occur. For example, a search based only on data in the management file may return frames instead of photos.</p>
206<p>Compare the image type in the management file with the image type retrieved from the JPEG metadata before operating on files. The following sample compares the two sources of information.</p>
207<p><pre style="border:1px solid; black; padding:8px;">
208// Get image type from the management file
209TCLPictureInfo* pPicInfo = NULL;
210TCL_SearchNextPictureInfo( ,, &pPicInfo ,, );
211
212// The manufacturer's note structure gotten from the manufacturer's note after decoding
213// See the JPEG library to learn how to get this
214// Cast the DSi camera manufacturer note to the following structure.
215TCLMakerNote* pMakerNote = ...;
216
217// Perform this process only if the image types match
218if ( TCL_IsSameImageType( pPicInfo , pMakerNote ) != FALSE )
219{
220    :
221}
222</pre></p>
223<p>This evaluation procedure is not necessary if you want to handle photos and frames together without differentiating between the two.</p>
224
225<hr><p>CONFIDENTIAL</p></body>
226</html>
227