1 /*---------------------------------------------------------------------------*
2 
3   Copyright (C) 2010-2012 Nintendo.  All rights reserved.
4 
5   These coded instructions, statements, and computer programs contain
6   proprietary information of Nintendo of America Inc. and/or Nintendo
7   Company Ltd., and are protected by Federal copyright law.  They may
8   not be disclosed to third parties or copied or duplicated in any form,
9   in whole or in part, without the prior written consent of Nintendo.
10 
11  *---------------------------------------------------------------------------*/
12 // -----------------------------------------------------------------------------
13 //  demoCapture.h
14 //
15 // -----------------------------------------------------------------------------
16 #ifndef __DEMO_CAPTURE_H_
17 #define __DEMO_CAPTURE_H_
18 
19 #include <cafe/demo.h>
20 
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24 
25 /// @addtogroup demoCapture
26 /// @{
27 
28 /// \brief supported demo capture format
29 typedef enum _DEMOCaptureFormat
30 {
31     I8,
32     I16,
33     RGBA8,
34     SRGB8
35 } DEMOCaptureFormat;
36 
37 /// \brief Data for demo capture
38 typedef struct _DEMOCaptureDataStore {
39     DEMOCaptureFormat captureFormat;
40     GX2ColorBuffer colorBuffer;
41     u8 *TGAData;
42     u32 TGALength;
43 } DEMOCaptureDataStore;
44 
45 extern DEMOCaptureDataStore DEMOCaptureData;
46 
47 /// \brief Demo
48 extern GX2ColorBuffer DEMOCaptureBuffer;
49 
50 /// \brief Sets up surface for demo capture.
51 ///
52 /// The capture API allows you to copy a surface to the capture surface.
53 /// This function must be called first to set up that surface.
54 /// Various capture formats are supported (see \ref DEMOCaptureFormat).
55 /// Can be called as necessary to reconfigure.
56 ///
57 /// Format can be I8, I16, RGBA8, or SRGB8.
58 /// For I8 & I16, capture always grabs the first (R) component of source.
59 /// Number format is always UNORM.
60 ///
61 /// \param width   width of capture surface
62 /// \param height  height of capture surface
63 /// \param format  format for capture surface & file
64 void DEMOCaptureInit(u32 width, u32 height, DEMOCaptureFormat format);
65 
66 /// \brief Frees resources used for demo capture.
67 ///
68 void DEMOCaptureShutdown(void);
69 
70 /// \brief Copies the specified src surface src to the dst file.
71 ///
72 /// If dstFilePath == NULL, capture to buffer only.
73 /// If dstFilePath == "", write captured image to serial output.
74 /// If srcBuffer == NULL, use a previously captured image.
75 ///
76 /// If the pathname begins with '/', it is used as an absolute path name.
77 /// If it does not, then "/vol/content/" is pre-prended to the path name
78 /// (this is done by DEMOFS).
79 ///
80 /// \note If /vol/content has been remapped to use DVDFS, then you may not
81 ///       open files there in "w" (write) mode.  Use /vol/save instead.
82 ///
83 /// \note For serial output, data is written using UUENCODE format.
84 ///       You must uudecode the captured output to convert to binary.
85 ///       (Install cygwin uudecode.exe from sharutils package.)
86 ///       This is done to overcome serial capture limitations.
87 ///       See http://en.wikipedia.org/wiki/Uuencode for details.
88 ///
89 /// \note You must call \ref DEMOCaptureInit before calling this function.
90 ///
91 /// The output file is in TGA format with RLE compression.
92 /// - I8 format = 8-bit grayscale TGA
93 /// - I16 format = 16-bit grayscale TGA
94 /// - RGBA8 = 32-bit full color with alpha TGA
95 /// - SRGB8 = 32-bit non-linear color with alpha TGA<p>
96 /// See http://en.wikipedia.org/wiki/Truevision_TGA for more details.
97 ///
98 /// GX2 tests/demos in the SDK can capture an image using the following make command,
99 /// where # is the frame number you wish to capture:
100 /// \verbatim make run RUN_ARGS="CAPTURE_SELECT=#" \endverbatim
101 /// The image is saved as: $CAFE_SAVE_DIR/common/GX2Capture.tga
102 ///
103 /// \param srcBuffer  Pointer to buffer to capture (typically DEMOColorBuffer)
104 /// \param dstFilePath  Path name to capture file to write, or NULL for serial output
105 ///
106 void DEMOCaptureCopy(GX2ColorBuffer *srcBuffer, const char *dstFilePath);
107 
108 /// @} // demoCapture
109 
110 #ifdef __cplusplus
111 }
112 #endif
113 
114 #endif // _DEMO_FONT_H_
115 
116