1 /* Copyright  (C) 2010-2019 The RetroArch team
2  *
3  * ---------------------------------------------------------------------------------------
4  * The following license statement only applies to this file (gfx_thumbnail_path.c).
5  * ---------------------------------------------------------------------------------------
6  *
7  * Permission is hereby granted, free of charge,
8  * to any person obtaining a copy of this software and associated documentation files (the "Software"),
9  * to deal in the Software without restriction, including without limitation the rights to
10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
11  * and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
16  * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
19  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21  */
22 
23 #ifndef __GFX_THUMBNAIL_PATH_H
24 #define __GFX_THUMBNAIL_PATH_H
25 
26 #include <retro_common_api.h>
27 #include <libretro.h>
28 
29 #include <boolean.h>
30 
31 #include "../playlist.h"
32 
33 RETRO_BEGIN_DECLS
34 
35 /* Note: This implementation reflects the current
36  * setup of:
37  * - menu_driver_set_thumbnail_system()
38  * - menu_driver_set_thumbnail_content()
39  * - menu_driver_update_thumbnail_path()
40  * This is absolutely not the best way to handle things,
41  * but I have no interest in rewriting the existing
42  * menu code... */
43 
44 enum gfx_thumbnail_id
45 {
46    GFX_THUMBNAIL_RIGHT = 0,
47    GFX_THUMBNAIL_LEFT
48 };
49 
50 /* Prevent direct access to gfx_thumbnail_path_data_t members */
51 typedef struct gfx_thumbnail_path_data gfx_thumbnail_path_data_t;
52 
53 /* Initialisation */
54 
55 /* Creates new thumbnail path data container.
56  * Returns handle to new gfx_thumbnail_path_data_t object.
57  * on success, otherwise NULL.
58  * Note: Returned object must be free()d */
59 gfx_thumbnail_path_data_t *gfx_thumbnail_path_init(void);
60 
61 /* Resets thumbnail path data
62  * (blanks all internal string containers) */
63 void gfx_thumbnail_path_reset(gfx_thumbnail_path_data_t *path_data);
64 
65 /* Utility Functions */
66 
67 /* Fetches the thumbnail subdirectory (Named_Snaps,
68  * Named_Titles, Named_Boxarts) corresponding to the
69  * specified 'type index' (1, 2, 3).
70  * Returns true if 'type index' is valid */
71 bool gfx_thumbnail_get_sub_directory(unsigned type_idx, const char **sub_directory);
72 
73 /* Returns true if specified thumbnail is enabled
74  * (i.e. if 'type' is not equal to MENU_ENUM_LABEL_VALUE_OFF) */
75 bool gfx_thumbnail_is_enabled(gfx_thumbnail_path_data_t *path_data, enum gfx_thumbnail_id thumbnail_id);
76 
77 /* Setters */
78 
79 /* Sets current 'system' (default database name).
80  * Returns true if 'system' is valid.
81  * If playlist is provided, extracts system-specific
82  * thumbnail assignment metadata (required for accurate
83  * usage of gfx_thumbnail_is_enabled())
84  * > Used as a fallback when individual content lacks an
85  *   associated database name */
86 bool gfx_thumbnail_set_system(gfx_thumbnail_path_data_t *path_data, const char *system, playlist_t *playlist);
87 
88 /* Sets current thumbnail content according to the specified label.
89  * Returns true if content is valid */
90 bool gfx_thumbnail_set_content(gfx_thumbnail_path_data_t *path_data, const char *label);
91 
92 /* Sets current thumbnail content to the specified image.
93  * Returns true if content is valid */
94 bool gfx_thumbnail_set_content_image(gfx_thumbnail_path_data_t *path_data, const char *img_dir, const char *img_name);
95 
96 /* Sets current thumbnail content to the specified playlist entry.
97  * Returns true if content is valid.
98  * > Note: It is always best to use playlists when setting
99  *   thumbnail content, since there is no guarantee that the
100  *   corresponding menu entry label will contain a useful
101  *   identifier (it may be 'tainted', e.g. with the current
102  *   core name). 'Real' labels should be extracted from source */
103 bool gfx_thumbnail_set_content_playlist(gfx_thumbnail_path_data_t *path_data, playlist_t *playlist, size_t idx);
104 
105 /* Updaters */
106 
107 /* Updates path for specified thumbnail identifier (right, left).
108  * Must be called after:
109  * - gfx_thumbnail_set_system()
110  * - gfx_thumbnail_set_content*()
111  * ...and before:
112  * - gfx_thumbnail_get_path()
113  * Returns true if generated path is valid */
114 bool gfx_thumbnail_update_path(gfx_thumbnail_path_data_t *path_data, enum gfx_thumbnail_id thumbnail_id);
115 
116 /* Getters */
117 
118 /* Fetches the current thumbnail file path of the
119  * specified thumbnail 'type'.
120  * Returns true if path is valid. */
121 bool gfx_thumbnail_get_path(gfx_thumbnail_path_data_t *path_data, enum gfx_thumbnail_id thumbnail_id, const char **path);
122 
123 /* Fetches current 'system' (default database name).
124  * Returns true if 'system' is valid. */
125 bool gfx_thumbnail_get_system(gfx_thumbnail_path_data_t *path_data, const char **system);
126 
127 /* Fetches current content path.
128  * Returns true if content path is valid. */
129 bool gfx_thumbnail_get_content_path(gfx_thumbnail_path_data_t *path_data, const char **content_path);
130 
131 /* Fetches current thumbnail label.
132  * Returns true if label is valid. */
133 bool gfx_thumbnail_get_label(gfx_thumbnail_path_data_t *path_data, const char **label);
134 
135 /* Fetches current thumbnail core name.
136  * Returns true if core name is valid. */
137 bool gfx_thumbnail_get_core_name(gfx_thumbnail_path_data_t *path_data, const char **core_name);
138 
139 /* Fetches current database name.
140  * Returns true if database name is valid. */
141 bool gfx_thumbnail_get_db_name(gfx_thumbnail_path_data_t *path_data, const char **db_name);
142 
143 /* Fetches current thumbnail image name
144  * (name is the same for all thumbnail types).
145  * Returns true if image name is valid. */
146 bool gfx_thumbnail_get_img_name(gfx_thumbnail_path_data_t *path_data, const char **img_name);
147 
148 /* Fetches current content directory.
149  * Returns true if content directory is valid. */
150 bool gfx_thumbnail_get_content_dir(gfx_thumbnail_path_data_t *path_data, char *content_dir, size_t len);
151 
152 RETRO_END_DECLS
153 
154 #endif
155