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>Nintendo DSi Photo Database Library (TCL)</title>
6<link rel="stylesheet" href="../css/nitro.css">
7</head>
8<body>
9<h1>Nintendo DSi Photo Database Library (TCL)</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 cameras and writing JPEG images to paths that can be loaded by Nintendo 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 Corresponding 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>The following processes demonstrate error handling when a management file fails to be loaded.</p>
22<ul>
23<li><b>Show a message prompting the user to start the Nintendo DSi Camera and use it to reference system memory and then stop further processing.</b></li>
24<li>Recreate the management file.</li>
25</ul>
26<p>There is little possibility that loading the management file in system memory will fail and recovery can be performed with the Nintendo 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 for attempting to recover a management file for reasons associated with the game's characteristics. However, even if the following processes are performed, management files might not be recovered.</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 fails.</p>
31<p>The error-handling sequences are explained in the following sections.</p>
32<h3>When Images Can Only Be Loaded</h3>
33<p>This sequence loads a management file that includes an error process when only 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 Can Be Loaded and Written</h3>
75<p>When images can be loaded and written as per application specifications, this management file loading sequence includes an error-handling process.</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 succeeded
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: // A file already exists in the next save location
94    case TCL_RESULT_ERROR_ALREADY_MANAGED: // The  next save location is already being 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 neither be 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 neither be 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 Nintendo 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 with the Nintendo 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 Nintendo 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 when a management file is created in this state.</p>
155<p><pre style="border:1px solid; black; padding:8px;">
156Creating a photo management file...
157
158</pre></p>
159<p></p>
160<h3>When Recreating Because the Management File Could Not Be Loaded</h3>
161<p>The following message is displayed when the management file is recreated for some other reason.</p>
162<p><pre style="border:1px solid; black; padding:8px;">
163The photo management file is corrupted.
164
165
166Recreating the photo management file.
167
168</pre></p>
169<p></p>
170
171<h2>Writing Image Files</h2>
172<p>Image files cannot be written in the following situations.</p>
173<dl>
174<dd>There is insufficient NAND
175<dd>The maximum manageable number of photos is already being managed
176<dd>An addressable path does not exist for the save location
177</dl>
178<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.
179</p>
180
181<p><pre style="border:1px solid; black; padding:8px;">
182// Flags that maintain whether addressable path exists.
183// If <CODE>TCL_RESULT_ERROR_NO_NEXT_INDEX</CODE> is returned from <CODE>TCL_RepairTable</CODE> or <CODE>TCL_CreateTable</CODE>, no path can be specified so the default value is set to <CODE>FALSE</CODE>.
184//
185BOOL isEnableValidPath;
186
187// Where image is actually stored
188// Only take photo if 1 or more photos can be taken and there is a valid path
189if ( TCL_CalcNumEnableToTakePictures(,,) &gt; 0 && isEnableValidPath != FALSE )
190{
191    result = TCL_EncodeAndWritePicture(,,);
192
193    // If, as a result of this save, there is no longer a valid path, hold this
194    if ( result == TCL_RESULT_ERROR_NO_NEXT_INDEX )
195    {
196        isEnableValidPath = FALSE;
197    }
198}
199</pre></p>
200<p>
201For more information, see the <CODE>tcl-2</CODE> demo.
202</p>
203
204<h2>JPEG Decoding</h2>
205<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>
206
207<h2>Differentiating Image Types</h2>
208<p>There are two types of images used with the Nintendo 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>
209<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>
210<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>
211<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>
212<p><pre style="border:1px solid; black; padding:8px;">
213// Get image type from the management file
214TCLPictureInfo* pPicInfo = NULL;
215TCL_SearchNextPictureInfo( ,, &pPicInfo ,, );
216
217// The manufacturer's note structure gotten from the manufacturer's note after decoding
218// See the JPEG library to learn how to get this
219// Cast the Nintendo DSi camera manufacturer note to the following structure.
220TCLMakerNote* pMakerNote = ...;
221
222// Perform this process only if the image types match
223if ( TCL_IsSameImageType( pPicInfo , pMakerNote ) != FALSE )
224{
225    :
226}
227</pre></p>
228<p>That this evaluation procedure is not necessary if you want to handle photos and frames together without differentiating between the two.</p>
229
230<H2>Revision History</H2>
231<P>
2322009/04/13 Initial version.
233</p>
234
235<hr><p>CONFIDENTIAL</p></body>
236</html>
237