Author: Harald Oehlmann <[email protected]>
State: Draft
Type: Project
Created: 04-Mar-2025
Tcl-Version: 9.1
Tk-Branch: tip-714-image-driver-info
Keywords: photo
Abstract
This TIP proposes to add a script-level communication channel with the image type handler. The application within this TIP is to introspect tk image photo format handlers.
Background
The original request is this Tk ticket 1441f8. A practical application of the proposed image handler photo formats command is as follows. The list of photo image formats is used to filter supported image file types in a file search box file type choice:
set formatlist [image handler photo formats]
set filetypelist {}
foreach format {gif png jpg} {
if {$format in $formatlist} {lappend filetypelist [list $format .$format]}
}
tk_getOpenFile -filetypes $filetypelist
Another application is performance. The photo handler will test the given data for any format, if no -format option is given. Using this option, a format option may be created on run-time. If no format is available, an error message may be issued.
The 3rd application is to avoid the handling of image data by the default handler. If no other handler takes the data, the default handler is always used. Then, the data is seen as a tcl list, which often leads to strange error messages or corrupt images.
Rationale
A framework for communication is established from the script level to the image type handler without the need of an image creation.
The application of this communication possibility is to query the list of supported photo formats in the processing order.
Specification
proposed option
The proposed new option to the image command is:
image handler type args
The arguments are passed to the image type handler specified by the argument type. The image type handler will process args and issue a result.
If the image type handler does not handle the option handler (e.g. NULL pointer in the interface), an error message is returned.
suboption formats
The suboption formats is proposed to the photo image as follows:
image handler photo formats
which returns the list of currently registered photo image formats in the search order which data is tested, if no -format option is given on image creation.
A current standard installation returns:
% image handler photo formats
svg ppm png gif default
suboption capabilities
The suboption capabilities is proposed to the photo image as follows:
image handler photo capabilities format
This command will return a list of capability indexes of the given format.
The possible indexes are:
- -file: this option is supported with the creation or configure suboption for this format.
- -data: this option is supported with the creation or configure suboption for this format.
- data: the option data -format format is supported.
- write: the option write -format format is supported.
- metadata: if the metadata option is handled by this format.
Those indexes correspond to the fact, how a photo image format is registered. The metadata flag is set for version 3 formats. The other options are set, if the corresponding function pointer is not NULL.
proposed C interface
An image type handler is registered on by:
void Tk_CreateImageType(const Tk_ImageType *typePtr);
The passed structure Tk_ImagType is extended by the image handler command implementation pointer. If this pointer is NULL, then there is no implementation for the image handler command. This is required for backward compatibility.
This results in the following structure:
typedef struct {
const char *name;
Tk_ImageCreateProc *createProc;
Tk_ImageGetProc *getProc;
Tk_ImageDisplayProc *displayProc;
Tk_ImageFreeProc *freeProc;
Tk_ImageDeleteProc *deleteProc;
struct Tk_ImageType *nextPtr;
Tk_ImageHandlerProc *handlerProc;
} \fBTk_ImageType;
The former definition of the last parameter was:
char *reserved;
The new type Tk_ImageHandlerProc is defined as follows:
typedef int (Tk_ImageHandlerProc) (Tcl_Interp *interp,
Tcl_Size objc, Tcl_Obj *const objv[]);
The parameters are the current interpreter and the script level parameters (args in image handler type args...). The function sets the interpreter result and returns the TCL result code.
Compatibility
Public structure redefinition
The image registration structure changed. Compatibility remains, if this reserved parameter is passed as a zero pointer. I am not aware of any custom use of this function, expect for the core implementations.
image command shortcut
The command image h will stop being a shortcut for image height.
Discussion
Public structure redefinition
The public structure registration may:
- Be modified by the insertion of handlerProc after deleteProc
- May get a new register function with the new structure, leading to two register functions and two stubs entries.
This is a crucial point. Opinions welcome!
Command name
The command image handler is not very intuitive.
Other possible names:
- image typeinfo: by Emiliano, see below
- tk::unsupported::typeinfo: by Emiliano, see below
- image handlercmd: to indicate, that a command is executed within the handlers scope
- image driver: this was the first proposal
Emilianos contriubtion
2025-03-29 on the core list:
A few comments about the terminology and the current image infrastructure.
Photo and bitmap are image types, not handlers. We already have a command to list those
% image types
photo bitmap
and a command to identify which type an instance image belongs to
% image type [lindex [image names] 0]
photo
The type is the first abstraction below Tk images, and if any further info on image types is required (such as what image formats it supports, color spaces, transparency, etc), I think is better to make this explicit in the command name. While I don't like it completely, image typeinfo $type might be more intuitive on what the command does.
And here is where things goes awry. Image managers are not required to provide an API for querying information about the type. While they indeed keep a lot of information in the type manager, there's no standard way to get such information through the type.
If we are talking specifically about the photo type (which Tk core owns) feels like cheating to extract information about it without a proper infrastructure in place. Should other type managers be creative and provide info through non-standard methods?
So my opinion is that what is needed is a proper infrastructure to extract type information from type managers themselves and not skip the type to provide direct access to a piece of information from a particular type.
Note that I'm not speaking hypotetically. There are other image types in the wild. The current version of the Blt toolkit implements a "picture" image type, with a lot of formats and image operations that we would love to have. For some info see BLT picture
In conclusion, I think this functionality is valuable but also think we need more machinery in place to get this right. Something to discuss is the format in which such information is returned. If a dictionary is agreed upon, then a key such as "formats" or "-format" might be used to retrieve such info.
In the meantime, Tk could implement it in some unsupported way, like [tk::unsupported::typeinfo photo formats]. This way it can be trivially converted to the proper infrastructure when (if) it becomes available.
possible extensions
This proposal only impelements a communication channel and two suboptions and only for the photo type.
Many extensions are possible:
- Establish a communication channel to the photo format handlers, like default value setting. This requires a revised photo format interface not handled here.
- Propose suboptions for other image types like the bitmap type or custom types like the BLT picture type.
- Implement high-level commands for multiple image type handlers. The proposed format suboption may also be valid for the picture image type. A generic image formats command may be implemented on the script level, using the commands proposed in this TIP.
Reference Implementation
A reference impementation can be found in Tk branch tip-714-image-driver-info.
Copyright
This document has been placed in the public domain.