What behavior do you want? From your concern about devices, I am guessing you want some level of portability.
What is the case use? There could be more sensible for different use cases (e.g.for photo manipulation, procedural animation, scientific simulations, game development, etc...)
I would argue that it is best to provide the width and height (in whatever units you use) of the available space to the script, and let the developer figure out if they want to scale the picture...
Sometimes the developer may want an image to have the same physical size. In which case providing the width and height in physical units (e.g. mm) is useful. However, sometimes the developer may want the same size in pixels, or the same proportion of the available space.
Also consider that for the developer, sometimes knowing that something is smaller than a pixel is useful, and sometimes patterns need to be pixel perfect.
Consider the following examples:
- If I write a script that generate a fractal, I want to have the best resolution possible for the device, as to show as much detail. And I also want to know how big pixels are, so that I do not generate more detail than needed.
- If I am using the code to generate dithering, or if I want to apply a convolution (I mean, a kernel as understood in image processing) on an image, I will also need to know the size in pixels.
- On the other hand, if I want to provide an onscreen ruler, that the user can actually use to measure things, I want to make sure it has the same physical units.
- Then again, if am creating animation for a movie, I want everything to scale with the device.
- There will be edge cases, for example, if I am adding a QR-code, I may want it to scale... but not to be smaller than a given physical size to make sure that cameras can pick it up.
- In fact, something similar happens once you add text to the problem (you do not want text to become too small), which will make you consider font relative units (at least provide a way to query how big a given text would be on a given font).
Thus, I would argue to provide sizes in both: pixel and some physical units (e.g. mm). If the developer wants to work in proportion of the available space, they can compute the proportions. If they want to figure out the ratio of pixels and physical units, they can do that, and if they want to do something else, they probably can do that too.
For your consideration: You could support annotated units in your script. See the example of CSS, in particular with calc which allows you to compute with different measurements units (e.g. five pixels from the center of the screen).
With that said, between physical units and pixels for the primitive call: prefer pixels. They are more versatile (assuming the developer can know the proportion to physical units). Why? Refer to the examples above, physical units only get you so far. Also, they would work in contexts that are not attached to physical units, which will also help in porting code from another platform.