Start changing GDISP images to use a simpler API based on GFILE's.

1 files changed, 61 insertions, 129 deletions

diff --git a/include/gdisp/image.h b/include/gdisp/image.h
index ff2e9d85..f8c5f6a1 100644
--- a/include/gdisp/image.h
+++ b/include/gdisp/image.h
@@ -40,6 +40,7 @@ typedef uint16_t	gdispImageError;
 	#define GDISP_IMAGE_ERR_UNSUPPORTED			(GDISP_IMAGE_ERR_UNRECOVERABLE+3)
 	#define GDISP_IMAGE_ERR_UNSUPPORTED_OK		3
 	#define GDISP_IMAGE_ERR_NOMEMORY			(GDISP_IMAGE_ERR_UNRECOVERABLE+4)
+	#define GDISP_IMAGE_ERR_NOSUCHFILE			(GDISP_IMAGE_ERR_UNRECOVERABLE+5)
 
 /**
  * @brief	Image flags
@@ -116,59 +117,78 @@ typedef struct gdispImage {
 extern "C" {
 #endif
 
-	/**
-	 * @brief	Sets the io fields in the image structure to routines
-	 * 			that support reading from an image stored in RAM or Flash.
-	 * 			
-	 * @return	TRUE if the IO open function succeeds
-	 *
-	 * @param[in] img   	The image structure
-	 * @param[in] memimage	A pointer to the image in RAM or Flash 
-	 *
-	 * @note	Always returns TRUE for a Memory Reader
-	 */
-	bool_t gdispImageSetMemoryReader(gdispImage *img, const void *memimage);
+	gdispImageError DEPRECATED("If possible please use gdispImageOpenFile(), gdispImageOpenMemory() or gdispImageOpenBaseFileStream() instead")
+					gdispImageOpen(gdispImage *img);
+	bool_t DEPRECATED("Use gdispImageOpenMemory() instead. GFX_USE_GFILE, GFILE_NEED_MEMFS must also be TRUE") gdispImageSetMemoryReader(gdispImage *img, const void *memimage);
+	#if GFX_USE_OS_CHIBIOS
+		bool_t DEPRECATED("Use gdispImageOpenBaseFileStream() instead. GFX_USE_GFILE, GFILE_NEED_CHIBIOSFS must also be TRUE") gdispImageSetBaseFileStreamReader(gdispImage *img, void *BaseFileStreamPtr);
+	#endif
+	#if defined(WIN32) || GFX_USE_OS_WIN32 || GFX_USE_OS_LINUX || GFX_USE_OS_OSX
+		bool_t DEPRECATED("Please use gdispImageOpenFile() instead. GFX_USE_GFILE must also be TRUE")
+				gdispImageSetFileReader(gdispImage *img, const char *filename);
+		#define gdispImageSetSimulFileReader(img, fname)	gdispImageSetFileReader(img, fname)
+	#endif
 
-	#if GFX_USE_OS_CHIBIOS || defined(__DOXYGEN__)
+	#if GFX_USE_GFILE || defined(__DOXYGEN__)
 		/**
-		 * @brief	Sets the io fields in the image structure to routines
-		 * 			that support reading from an image stored on a BaseFileStream (eg SDCard).
+		 * @brief	Open an image in a file and get it ready for drawing
+		 * @details	Determine the image format and get ready to decode the first image frame
+		 * @return	GDISP_IMAGE_ERR_OK (0) on success or an error code.
 		 *
-		 * @return	TRUE if the IO open function succeeds
+		 * @pre		GFX_USE_GFILE must be TRUE and you must have included the file-system support
+		 * 			you want to use.
 		 *
-		 * @param[in] img   			The image structure
-		 * @param[in] BaseFileStreamPtr	A pointer to the (open) BaseFileStream object.
+		 * @param[in] img  		The image structure
+		 * @param[in] filename	The filename to open
 		 *
+		 * @note	This determines which decoder to use and then initialises all other fields
+		 * 			in the gdispImage structure.
+		 * @note	The image background color is set to White.
+		 * @note	There are three types of return - everything OK, partial success and unrecoverable
+		 * 			failures. For everything OK it returns GDISP_IMAGE_ERR_OK. A partial success can
+		 * 			be distinguished from a unrecoverable failure by testing the GDISP_IMAGE_ERR_UNRECOVERABLE
+		 * 			bit in the error code.
+		 * 			A partial success return code means an image can still be drawn but perhaps with
+		 * 			reduced functionality eg only the first page of a multi-page image.
+		 * @note	@p gdispImageClose() should be called even after a partial failure in order to
+		 * 			properly close the file.
 		 */
-		bool_t gdispImageSetBaseFileStreamReader(gdispImage *img, void *BaseFileStreamPtr);
+		gdispImageError gdispImageOpenFile(gdispImage *img, const char *filename);
 	#endif
-
-	#if defined(WIN32) || GFX_USE_OS_WIN32 || GFX_USE_OS_LINUX || GFX_USE_OS_OSX || defined(__DOXYGEN__)
+	
+	#if GFX_USE_OS_CHIBIOS || defined(__DOXYGEN__)
 		/**
-		 * @brief	Sets the io fields in the image structure to routines
-		 * 			that support reading from an image stored in Win32 simulators native
-		 * 			file system.
-		 * @pre		Only available on the Win32 simulator
+		 * @brief	Open an image in a ChibiOS basefilestream and get it ready for drawing
+		 * @details	Determine the image format and get ready to decode the first image frame
+		 * @return	GDISP_IMAGE_ERR_OK (0) on success or an error code.
 		 *
-		 * @return	TRUE if the IO open function succeeds
+		 * @pre		This only makes sense on the ChibiOS operating system.
 		 *
-		 * @param[in] img   	The image structure
-		 * @param[in] filename	The filename to open
+		 * @param[in] img  				The image structure
+		 * @param[in] BaseFileStreamPtr	A pointer to an open BaseFileStream
 		 *
+		 * @note	This determines which decoder to use and then initialises all other fields
+		 * 			in the gdispImage structure.
+		 * @note	The image background color is set to White.
+		 * @note	There are three types of return - everything OK, partial success and unrecoverable
+		 * 			failures. For everything OK it returns GDISP_IMAGE_ERR_OK. A partial success can
+		 * 			be distinguished from a unrecoverable failure by testing the GDISP_IMAGE_ERR_UNRECOVERABLE
+		 * 			bit in the error code.
+		 * 			A partial success return code means an image can still be drawn but perhaps with
+		 * 			reduced functionality eg only the first page of a multi-page image.
+		 * @note	@p gdispImageClose() should be called even after a partial failure in order to
+		 * 			properly close the file.
 		 */
-		bool_t gdispImageSetFileReader(gdispImage *img, const char *filename);
-		/* Old definition */
-		#define gdispImageSetSimulFileReader(img, fname)	gdispImageSetFileReader(img, fname)
+		gdispImageError gdispImageOpenBaseFileStream(gdispImage *img, void *BaseFileStreamPtr);
 	#endif
-	
+
 	/**
-	 * @brief	Open an image ready for drawing
+	 * @brief	Open an image in memory and get it ready for drawing
 	 * @details	Determine the image format and get ready to decode the first image frame
 	 * @return	GDISP_IMAGE_ERR_OK (0) on success or an error code.
 	 * 
-	 * @param[in] img   The image structure
-	 * 
-	 * @pre		The io fields should be filled in before calling gdispImageOpen()
+	 * @param[in] img  		The image structure
+	 * @param[in] memimage	A pointer to the image bytes in memory
 	 * 
 	 * @note	This determines which decoder to use and then initialises all other fields
 	 * 			in the gdispImage structure.
@@ -179,17 +199,17 @@ extern "C" {
 	 * 			bit in the error code.
 	 * 			A partial success return code means an image can still be drawn but perhaps with
 	 * 			reduced functionality eg only the first page of a multi-page image.
-	 * @note	@p gdispImageClose() can be called even after a failure to open the image to ensure
-	 * 			that the IO close routine gets called.
+	 * @note	@p gdispImageClose() should be called even after a partial failure in order to
+	 * 			properly close the file.
 	 */
-	gdispImageError gdispImageOpen(gdispImage *img);
-	
+	gdispImageError gdispImageOpenMemory(gdispImage *img, const void *memimage);
+
 	/**
 	 * @brief	Close an image and release any dynamically allocated working storage.
 	 * 
 	 * @param[in] img   The image structure
 	 * 
-	 * @pre		gdispImageOpen() must have returned successfully.
+	 * @pre		gdispImageOpenFile() must have returned successfully.
 	 *
 	 * @note	Also calls the IO close function (if it hasn't already been called).
 	 */
@@ -282,94 +302,6 @@ extern "C" {
 	 */
 	delaytime_t gdispImageNext(gdispImage *img);
 	
-	#if GDISP_NEED_IMAGE_NATIVE
-		/**
-		 * @brief	The image drawing routines for a NATIVE format image.
-		 * 
-		 * @note	Only use these functions if you absolutely know the format
-		 * 			of the image you are decoding. Generally you should use the
-		 * 			generic functions and it will auto-detect the format.
-		 * @note	A NATIVE format image is defined as an 8 byte header described below, immediately
-		 * 			followed by the bitmap data. The bitmap data is stored in the native format for
-		 * 			the display controller. If the pixel format specified in the header does not
-		 * 			match the controller native format then the image is rejected.
-		 * @note	The 8 byte header:
-		 *  			{ 'N', 'I', width.hi, width.lo, height.hi, height.lo, format.hi, format.lo }
-		 *  			The format word = GDISP_PIXELFORMAT
-		 * @{
-		 */
-		gdispImageError gdispImageOpen_NATIVE(gdispImage *img);
-		void gdispImageClose_NATIVE(gdispImage *img);
-		gdispImageError gdispImageCache_NATIVE(gdispImage *img);
-		gdispImageError gdispGImageDraw_NATIVE(GDisplay *g, gdispImage *img, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t sx, coord_t sy);
-		delaytime_t gdispImageNext_NATIVE(gdispImage *img);
-		/* @} */
-	#endif
-
-	#if GDISP_NEED_IMAGE_GIF
-		/**
-		 * @brief	The image drawing routines for a GIF image.
-		 * @note	Only use these functions if you absolutely know the format
-		 * 			of the image you are decoding. Generally you should use the
-		 * 			generic functions and it will auto-detect the format.
-		 * @{
-		 */
-		gdispImageError gdispImageOpen_GIF(gdispImage *img);
-		void gdispImageClose_GIF(gdispImage *img);
-		gdispImageError gdispImageCache_GIF(gdispImage *img);
-		gdispImageError gdispGImageDraw_GIF(GDisplay *g, gdispImage *img, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t sx, coord_t sy);
-		delaytime_t gdispImageNext_GIF(gdispImage *img);
-		/* @} */
-	#endif
-
-	#if GDISP_NEED_IMAGE_BMP
-		/**
-		 * @brief	The image drawing routines for a BMP image.
-		 * @note	Only use these functions if you absolutely know the format
-		 * 			of the image you are decoding. Generally you should use the
-		 * 			generic functions and it will auto-detect the format.
-		 * @{
-		 */
-		gdispImageError gdispImageOpen_BMP(gdispImage *img);
-		void gdispImageClose_BMP(gdispImage *img);
-		gdispImageError gdispImageCache_BMP(gdispImage *img);
-		gdispImageError gdispGImageDraw_BMP(GDisplay *g, gdispImage *img, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t sx, coord_t sy);
-		delaytime_t gdispImageNext_BMP(gdispImage *img);
-		/* @} */
-	#endif
-	
-	#if GDISP_NEED_IMAGE_JPG
-		/**
-		 * @brief	The image drawing routines for a JPG image.
-		 * @note	Only use these functions if you absolutely know the format
-		 * 			of the image you are decoding. Generally you should use the
-		 * 			generic functions and it will auto-detect the format.
-		 * @{
-		 */
-		gdispImageError gdispImageOpen_JPG(gdispImage *img);
-		void gdispImageClose_JPG(gdispImage *img);
-		gdispImageError gdispImageCache_JPG(gdispImage *img);
-		gdispImageError gdispGImageDraw_JPG(GDisplay *g, gdispImage *img, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t sx, coord_t sy);
-		delaytime_t gdispImageNext_JPG(gdispImage *img);
-		/* @} */
-	#endif
-
-	#if GDISP_NEED_IMAGE_PNG
-		/**
-		 * @brief	The image drawing routines for a PNG image.
-		 * @note	Only use these functions if you absolutely know the format
-		 * 			of the image you are decoding. Generally you should use the
-		 * 			generic functions and it will auto-detect the format.
-		 * @{
-		 */
-		gdispImageError gdispImageOpen_PNG(gdispImage *img);
-		void gdispImageClose_PNG(gdispImage *img);
-		gdispImageError gdispImageCache_PNG(gdispImage *img);
-		gdispImageError gdispGImageDraw_PNG(GDisplay *g, gdispImage *img, coord_t x, coord_t y, coord_t cx, coord_t cy, coord_t sx, coord_t sy);
-		delaytime_t gdispImageNext_PNG(gdispImage *img);
-		/* @} */
-	#endif
-
 #ifdef __cplusplus
 }
 #endif