(Following on from this thread: Glk extension proposal: images in buffer windows )
The draft text for the Glk spec update:
extern glui32 glk_image_draw_scaled_ext(winid_t win, glui32 image,
glsi32 val1, glsi32 val2, glui32 width, glui32 height,
glui32 imagerule, glui32 maxwidth);
Another version of glk_image_draw(), with more options for image scaling.
The imagerule option encodes a width rule and a height rule. (You must supply one of each when calling this function.)
Width rules:
- imagerule_WidthOrig: Use the image’s standard width. The width argument is ignored.
- imagerule_WidthFixed: Use the width given in the width argument (as an integer).
- imagerule_WidthRatio: The image width will be proportional to the window width. The proportion is given by the width argument, which in this case is a fixed-point fraction. $10000 (1.0) means that the image width will be 100% of the window width. $8000 (0.5) means 50% of the window width, and so on.
Height rules:
- imagerule_HeightOrig: Use the image’s standard height. The height argument is ignored.
- imagerule_HeightFixed: Use the height given in the height argument (as an integer).
- imagerule_AspectRatio: The image height will be a fixed aspect ratio compared to the width. (The width is as defined above.) The height argument, in this case, is a fixed-point fraction which is multiplied by the image’s standard aspect ratio. $10000 (1.0) means that the image will always retain its original aspect ratio. $20000 (2.0) means that it will be stretched vertically by a factor of 2.
[Remember that imagerule_WidthRatio defines the image width relative to the window width. imagerule_AspectRatio defines the image height relative to the image width.]
The maxwidth argument, if nonzero, applies an additional upper bound based on the window width. It is treated as fixed-point fraction of the window width. If the image is wider than this, it is reduced proportionally.
[Thus if you use imagerule_WidthFixed, width=600, maxwidth=$10000, then the image will appear with a width of 600 or the window width, whichever is smaller. If you use imagerule_WidthOrig, maxwidth=$8000, then the image will appear with its original width or half the window width, whichever is smaller.]
[You can combine imagerule_AspectRatio with the above options. The interpreter always figures out the width first, then the height (again, imagerule_AspectRatio only controls height). Then it applies maxwidth, which may cause a proportional reduction (regardless of how height was determined).]
[Note that applying both imagerule_WidthRatio and maxwidth is pointless. The wider constraint will be ignored.]
[If the window is resized, what happens? This depends on the window type. See below.]
[glk_image_draw_scaled_ext() can do everything the previous two functions can do. glk_image_draw() is equivalent to imagerule_WidthOrig|imagerule_HeightOrig, maxwidth=$10000. glk_image_draw_scaled() is equivalent to imagerule_WidthFixed|imagerule_HeightFixed with the given size, maxwidth=$10000.]
…In a text buffer window, imagerule_WidthRatio is dynamically computed; the image width will always be relative to the current window width. If the text buffer window is resized (by the user or a window arrangement call), the image will resize too.
…The imagerule_WidthRatio option does not dynamically resize in a graphics window. The image size is computed when glk_image_draw_scaled_ext() is called, and then the image is painted to the canvas.
Also, the docs for glk_image_draw() and glk_image_draw_scaled() now have this note:
If the image is wider than the window it is drawn in, it will be proportionally reduced to fit with window width. This is a behavior change in Glk 0.7.6.
.
