//--- // gint:display - Drawing functions // // This module covers the drawing functions that are common to fx9860g and // fxcg50. Platform-specific definitions are found in // and . //--- #ifndef GINT_DISPLAY #define GINT_DISPLAY #ifdef __cplusplus extern "C" { #endif #include #include /* Platform-specific functions include VRAM management and the definition of the color_t type. */ #ifdef FX9860G #include #endif #ifdef FXCG50 #include #endif //--- // Video RAM management //--- /* dupdate(): Push the video RAM to the display driver This function makes the contents of the VRAM visible on the screen. It is the equivalent of Bdisp_PutDisp_DD() in most situations. On fx-9860G, this function also manages the gray engine settings. When the gray engine is stopped, it pushes the contents of the VRAM to screen, and when it is on, it swaps buffer and lets the engine's timer push the VRAMs to screen when suitable. To make the transition between the two modes smooth, dgray() does not enable the gray engine immediately; instead the first call to update() after dgray() switches the gray engine on and off. On fx-CG 50, because rendering is slow and sending data to screen is also slow, a special mechanism known as triple buffering is implemented. Two VRAMs are allocated, and frames are alternately rendered on each VRAM. When dupdate() is called to push one of the VRAMs to screen, it starts the DMA (which performs the push in the background) and immediately returns after switching to the other VRAM so that the user can draw during the push. The transfer from the DMA to the screen lasts about 10 ms if memory is available every cycle. Each access to the memory delays the transfer by a bit, so to fully use the available time, try to run AIs, physics or other calculation-intensive code rather than using the VRAM. Typical running time without overclock: fx-9860G: 1 ms (gray engine off) fx-9860G: ~30% of CPU time (gray engine on) fx-CG 50: 11 ms */ void dupdate(void); /* dupdate_set_hook(): Define a function to be called after each dupdate() This functions configures the update hook, which is called after each dupdate() has sent VRAM to the display (but before VRAMs are switched when triple-buffering is used on fx-CG 50). The hook is mostly useful to send a copy of the frame to another medium, typically through a USB connection to a projector-style application. See usb_fxlink_videocapture() in for an example. The function is an indirect call; create one with the GINT_CALL() macro from . Pass GINT_CALL_NULL to disable the feature. @function Indirect call to perform after each dupdate(). */ void dupdate_set_hook(gint_call_t function); /* dupdate_get_hook(): Get a copy of the dupdate() hook */ gint_call_t dupdate_get_hook(void); //--- // Rendering mode control //--- /* dmode: Rendering mode settings This structure indicates the current window settings. Rendering is limited to the rectangle spanning from (left,top) included, to (right,bottom) excluded. The default is from (0,0) to (DWIDTH,DHEIGHT). */ struct dwindow { int left, top; int right, bottom; }; extern struct dwindow dwindow; /* dwindow_set(): Set the rendering window This function changes [dwindow] settings to limit rendering to a sub-surface of the VRAM. Note that this doesn't change the coordinate system; the pixel at (DWIDTH/2, DHEIGHT/2) is always in the middle of the screen regardless of the window setting. However, it might be masked out by the window. Returns the old dwindow settings (if it needs to be restored later). */ struct dwindow dwindow_set(struct dwindow new_mode); //--- // Area rendering functions //--- /* dclear(): Fill the screen with a single color This function clears the screen by painting all the pixels in a single color. It is optimized for opaque colors; on fx-CG 50, it uses dma_memset() to fill in the VRAM. Typical running time without overclock: fx-9860G SH3: 70 µs fx-9860G SH4: 15 µs fx-CG 50: 2.5 ms (full-screen drect() is about 6 ms) On fx9860g, use drect() if you need operators that modify existing pixels instead of replacing them such as invert. @color fx-9860G: white light* dark* black fx-CG 50: Any R5G6B5 color *: When the gray engine is on, see dgray(). */ void dclear(color_t color); /* drect(): Fill a rectangle of the screen This functions applies a color or an operator to a rectangle defined by two points (x1 y1) and (x2 y2). Both are included in the rectangle. @x1 @y1 Top-left rectangle corner (included) @x2 @y2 Bottom-right rectangle corner (included) @color fx-9860G: white light* dark* black none invert lighten* darken* fx-CG 50: Any R5G6B5 color, C_NONE or C_INVERT *: When the gray engine is on, see dgray(). */ void drect(int x1, int y1, int x2, int y2, int color); /* drect_border(): Rectangle with border This function draws a rectangle with an inner border. The border width must be smaller than half the width and half the height. @x1 @y1 @x2 @y2 Top-left and bottom-right rectangle corners (included) @fill_color Center color (same values as drect() are allowed) @border_width Amount of pixels reserved for the border on each side @border_color Border color (same values as drect() are allowed) */ void drect_border(int x1, int y1, int x2, int y2, int fill_color, int border_width, int border_color); //--- // Point drawing functions //--- /* dpixel(): Change a pixel's color Paints the selected pixel with an opaque color or applies an operator to a pixel. Setting pixels individually is a slow method for rendering. Other functions that draw lines, rectangles, images or text will take advantage of possible optimizations to make the rendering faster, so prefer using them when they apply. On fx-9860G, if an operator such as invert is used, the result will depend on the current color of the pixel. @x @y Coordinates of the pixel to repaint @color fx-9860G: white light* dark* black none invert lighten* darken* fx-CG 50: Any R5G6B5 color, C_NONE or C_INVERT *: When the gray engine is on, see dgray(). */ void dpixel(int x, int y, int color); /* dgetpixel(): Get a pixel's color Returns the current color of any pixel in the VRAM. This function ignores the rendering window. Returns -1 if (x,y) is out of bounds. */ int dgetpixel(int x, int y); /* dline(): Render a straight line This function draws a line using a Bresenham-style algorithm. Please note that dline() may not render lines exactly like Bdisp_DrawLineVRAM(). dline() has optimizations for horizontal and vertical lines. The speedup for horizontal lines is about x2 on fx-CG 50 and probably about x30 on fx-9860G. Vertical lines have a smaller speedup. dline() is currently not able to clip arbitrary lines without calculating all the pixels, so drawing a line from (-1e6,0) to (1e6,395) will work but will be very slow. @x1 @y1 @x2 @y2 Endpoints of the line (both included). @color Line color (same values as dpixel() are allowed) */ void dline(int x1, int y1, int x2, int y2, int color); /* dhline(): Full-width horizontal line This function draws a horizontal line from the left end of the screen to the right end, much like the Basic command "Horizontal". @y Line number @color Line color (same values as dline() are allowed) */ void dhline(int y, int color); /* dvline(): Full-height vertical line This function draws a vertical line from the top end of the screen to the bottom end, much like the Basic command "Vertical". @x Column number @color Line color (same values as dline() are allowed) */ void dvline(int x, int color); //--- // Text rendering (topti) //--- /* font_t: Font data encoded for topti */ typedef struct { /* Font name (NUL-terminated), NULL if no title */ char const *name; /* Font shape flags */ uint bold :1; uint italic :1; uint serif :1; uint mono :1; uint :3; /* Whether data is variable-length (proportional font) */ uint prop :1; /* Line height */ uint8_t line_height; /* Storage height */ uint8_t data_height; /* Number of Unicode blocks */ uint8_t block_count; /* Number of total glyphs */ uint32_t glyph_count; /* Character spacing (usually 1) */ uint8_t char_spacing; uint :24; struct { /* Unicode point of first character in block */ uint start :20; /* Length of block */ uint length :12; } *blocks; /* Raw glyph data */ uint32_t *data; union { /* For monospaced fonts */ struct { /* Width of glyphs */ uint16_t width; /* Storage size, in longwords, of each glyph */ uint16_t storage_size; }; /* For proportional fonts */ struct { /* Storage index to find glyphs quickly */ uint16_t *glyph_index; /* Width of each individual glyph */ uint8_t *glyph_width; }; }; } GPACKED(4) font_t; /* dfont(): Set the default font for text rendering This function changes the default font for text rendering; this affects dtext_opt(), dtext() and the related functions. If the specified font is NULL, gint's default font is used instead. This function returns the previously configured font. Normally you want to restore it after you're done so as to not affect ambiant calls to text rendering functions. It would look like this: font_t const *old_font = dfont(new_font); // Do the text rendering... dfont(old_font); @font Font to use for subsequent text rendering calls Returns the previously configured font. */ font_t const *dfont(font_t const *font); /* dfont_default(): Get gint's default font On fx-9860G, the default font is a 5x7 font very close to the system's. On fx-CG 50, the default font is an original, proportional 8x9 font. */ font_t const *dfont_default(void); /* dsize(): Get the width and height of rendered text This function computes the size that the given string would take up if rendered with a certain font. If you specify a NULL font, the currently configured font will be used; this is different from dfont(), which uses gint's default font when NULL is passed. Note that the height of each glyph is not stored in the font, only the maximum. Usually this is what you want because vertically-centered strings must have the same baseline regardless of their contents. So the height set by dsize() is the same for all strings and only depends on the font. The height is computed in constant time, and the width in linear time. If the third argument is NULL, this function returns in constant time. @str String whose size must be evaluated @font Font to use; if NULL, defaults to the current font @w @h Set to the width and height of the rendered text, may be NULL */ void dsize(char const *str, font_t const *font, int *w, int *h); /* dnsize(): Get the width and height of rendered text, with character limit This function is similar to dsize(), but stops after (size) bytes If (size < 0), there is no limit and this function is identical to dsize(). @str String whose size must be evaluated @size Maximum number of bytes to read from (str) @font Font to use; if NULL, defaults to the current font @w @h Set to the width and height of the rendered text, may be NULL */ void dnsize(char const *str, int size, font_t const *font, int *w, int *h); /* drsize(): Get width of rendered text with reverse size limit This function is the opposite of dnsize(). It determines how many characters of (str) can fit into the specified (width), and returns a pointer to the first character after that section. If (w) is non-NULL, it it set to the width of the section, which is typically a couple of pixels smaller than the provided limit. @str String to read characters from @font Font to use; if NULL, defaults to the current font @width Maximum width @w Set to the width of the rendered text, may be NULL Returns a pointer to first character that doesn't fit, or end-of-str */ char const *drsize(char const *str, font_t const *font, int width, int *w); /* Alignment settings for dtext_opt() and dprint_opt(). Combining a vertical and a horizontal alignment option specifies where a given point (x,y) should be relative to the rendered string. */ enum { /* Horizontal settings: default in dtext() is DTEXT_LEFT */ DTEXT_LEFT = 0, DTEXT_CENTER = 1, DTEXT_RIGHT = 2, /* Vertical settings: default in dtext() is DTEXT_TOP */ DTEXT_TOP = 0, DTEXT_MIDDLE = 1, DTEXT_BOTTOM = 2, }; /* dtext_opt(): Display a string of text Draws some text in the video RAM using the font set with dfont() (or gint's default if no such font was set). This function has a lot of parameters, see dtext() for a simpler version. The alignment options specify where (x y) should be relative to the rendered string. The default is halign=DTEXT_LEFT and valign=DTEXT_TOP, which means that (x y) is the top-left corder of the rendered string. The different combinations of settings provide 9 positions of (x y) to choose from. On fx-9860G, due to the particular design of topti, this function performs drastic rendering optimizations using the line structure of the VRAM and renders 5 or 6 characters simultaneously. This is not a printf()-family function so str cannot contain formats like "%d" and you cannot pass additional arguments. See dprint_opt() and dprint() for that. @x @y Coordinates of the anchor of the rendered string @fg @bg Text color and background color fx-9860G: white light* dark* black none invert lighten* darken* fx-CG 50: Any R5G6B6 color, or C_NONE @halign Where x should be relative to the rendered string @valign Where y should be relative to the rendered string @str String to display @size Maximum number of bytes to display (negative for no limit) */ void dtext_opt(int x, int y, int fg, int bg, int halign, int valign, char const *str, int size); /* The last parameter @size was added in gint 2.4; this macro will add it automatically with a value of -1 if the call is made with only 7 parameters. This is for backwards compatibility. */ #define dtext_opt8(x,y,fg,bg,h,v,str,sz,...) dtext_opt(x,y,fg,bg,h,v,str,sz) #define dtext_opt(...) dtext_opt8(__VA_ARGS__, -1) /* dtext(): Simple version of dtext_opt() with defaults Calls dtext_opt() with bg=C_NONE, halign=DTEXT_LEFT and valign=DTEXT_TOP. */ void dtext(int x, int y, int fg, char const *str); /* dprint_opt(): Display a formatted string This function is exactly like dtext_opt(), but accepts printf-like formats with arguments. See for a detailed view of what this format supports. For example: dprint_opt(x, y, fg, bg, halign, valign, "A=%d B=%d", A, B); */ void dprint_opt(int x, int y, int fg, int bg, int halign, int valign, char const *format, ...); /* dprint(): Simple version of dprint_op() with defaults Calls dprint_opt() with bg=C_NONE, halign=DTEXT_LEFT and valign=DTEXT_TOP */ void dprint(int x, int y, int fg, char const *format, ...); //--- // Image rendering (bopti) //--- /* The bopti_image_t structure is platform-dependent, see and if you're curious. */ /* dimage(): Render a full image This function blits an image on the VRAM using gint's special format. It is a special case of dsubimage() where the full image is drawn with clipping. @x @y Coordinates of the top-left corner of the image @image Pointer to image encoded with fxconv for bopti */ void dimage(int x, int y, bopti_image_t const *image); /* Option values for dsubimage() */ enum { /* No option */ DIMAGE_NONE = 0x00, /* Disable clipping, ie. adjustments to the specified subrectangle and screen location such that any part that overflows from the image or the screen is ignored. Slightly faster. */ DIMAGE_NOCLIP = 0x01, }; /* dsubimage(): Render a section of an image This function blits a subrectangle [left, top, width, height] of an image on the VRAM. It is more general than dimage() and also provides a few options. @x @y Coordinates on screen of the rendered subrectangle @image Pointer to image encoded with fxconv for bopti @left @top Top-left coordinates of the subrectangle within the image @width @height Subrectangle dimensions @flags OR-combination of DIMAGE_* flags */ void dsubimage(int x, int y, bopti_image_t const *image, int left, int top, int width, int height, int flags); #ifdef __cplusplus } #endif #endif /* GINT_DISPLAY */