[editorial] Consider if there's a much better name for "image copies"

[kainino0x]

The term "image copy"/"ImageCopy" is used to describe buffer<->texture copies - copies from linear memory to non-linear (texture) memory.

Current name	Used in
GPUImageDataLayout	writeTexture
GPUImageCopyBuffer	T2B, B2T
GPUImageCopyTexture	T2B, B2T, T2T
GPUImageCopyTextureTagged	copyExternalImageToTexture
GPUImageCopyExternalImage	copyExternalImageToTexture
GPUImageCopyExternalImageSource	member of ^ dictionary

But the term "image" is quite overloaded in this domain: Vulkan VkImage, JS new Image(), HTML image, ....

We use these terms in the WebIDL, but only in dictionary names, which we can change without breaking the JS API. However, other language bindings need to put this name in their APIs, so I'd like to consider if we can come up with a better name now, and if it's worth some ecosystem churn to do so (webgpu.h/dawn/wgpu/wgpu-native/emscripten, typescript types, other bindings).

EDIT: We do use the term "image" in rowsPerImage however it's really not clear whether they're referring to the same concept. That was the intent, but it doesn't make a ton of sense.

[kainino0x]

Here is where we started using the name "image copy": #1375

[kainino0x]

Editor brainstorming:

image copy
texel
texel copy
copy view
location
footprint
extent
region
pointer
portion
origin
start
linear/non-linear
linear/?
slice (ambiguous)

Mull over the following ideas:

TextureCopyOrigin
TextureCopyDataLayout
TextureCopyBufferLayout

[Kangz]

IMHO we already discussed this with editors and came up with ImageCopyTexture and friends so extra churn isn't going to help that much. Image as describing a know layout of texels seems fine.

[kainino0x]

I forgot to link to the PR I was looking at, #1375 which was where we originally discussed the names we have now.

Currently I am pretty happy with TextureCopy{Origin,DataLayout,BufferLayout}. I do think they're better. It would also mean:
TextureCopyOriginTagged
TextureCopyExternalImage? ExternalImageCopyOrigin? TextureCopyExternalOrigin?

[kainino0x]

Jim/Kai discussion:

• Does it pass the bar of "much better"?
• K: Great to remove the word "image"
• J: Much easier to tell where the noun is. GPUImageCopyTexture is not a GPUTexture, and it's not a sentence "image(n) copy(v) texture(n)"
• "origin" confusing because it can be used as a destination? Not really, the only other place we use "origin" is for coordinate space origins, and "cross-origin" etc.
• Think it passes the bar for us and we should propose it.
• The other two names?
• J: See no problem with GPUTextureCopyOriginTagged
• ExternalImage? It's always the source of the copy. Only used in one place, unlikely to ever be used anywhere else (certainly not as a destination). Almost nothing in common with GPUTextureCopyOrigin
• Should definitely have "external" in it, could have "source" in it. Should probably have "external image" in it since that's in the function name copyExternalImageToTexture()
• Reasonable to make the name more specific to copyExternalImageToTexture(). That copy is pretty different from the other "texture copies" since it does color conversion and stuff.
• The "tagged" one is also only used here, could make its name more specific, like CopyExternalImageDestination. Though more plausible it could be used somewhere else someday.
• Oh, we need a name for GPUImageCopyExternalImageSource too. [Added to issue summary]
• GPUTextureCopyExternalImage / GPUTextureCopyExternalImageSource
• GPUExternalImageCopyOrigin / (GPUExternalImageCopySource or GPUExternalImageSource)
• GPUCopyExternalImageOrigin / GPUCopyExternalImageSource
• Prefer that last one for two reasons: mirrors the function name, and isn't confusable with GPUExternalTexture

Full proposal:

Old	New	Used in
GPUImageDataLayout	GPUTextureCopyDataLayout	writeTexture
GPUImageCopyBuffer	GPUTextureCopyBufferLayout	T2B, B2T
GPUImageCopyTexture	GPUTextureCopyOrigin	T2B, B2T, T2T, writeTexture
GPUImageCopyTextureTagged	GPUTextureCopyOriginTagged	copyExternalImageToTexture
GPUImageCopyExternalImage	GPUCopyExternalImageOrigin	copyExternalImageToTexture
GPUImageCopyExternalImageSource	GPUCopyExternalImageSource	member of ^ dictionary

(@jimblandy Writing this down, I could also go for replacing the "Tagged" one with GPUCopyExternalImageDestination if we want to solidify a terminology change to not call copyExternalImageToTexture() a "texture copy". Since it's tagged, it's inherently more complex than most "texture copies" which operate on nearly-raw data. However I am also fine with keeping it, because we can similarly say that once conversion is complete, the last step of copyExternalImageToTexture() is indeed a raw data copy.

EDIT: The "Tagged" lexeme is pretty useful for explaining what it is.)

[Kangz]

What about GPUTexelCopy instead of GPUImageCopy? Also GPUCopyExternalImageOrigin contains flipY which is weird for an "origin" that sounds just like a 2D location.

[kainino0x]

One thing I forgot about is that we do use the word image in in the API, in rowsPerImage. IIRC the intent was that the word "image" in GPUImageCopy* was the same as "image" in rowsPerImage, though honestly it's really not very clear that those are the same thing. By that logic, GPURowCopy* would have made just as much (or more) sense, but that name would be very unclear too.

[kdashg]

I don't think Origin makes this clearer, but maybe Desc[riptor]? (Also "origin" in web specs is usually talking about e.g. domains and same-origin stuff)

On "image", IIRC Image in (at least) GL/Vulkan is generally the term for a mip-level of a Texture, which is why copies to and from textures are "image copies", because such copies are done per-mip-level. (A Texture is a structured set of Images)

[kainino0x]

OK, sorry to waffle (since I said in the meeting we probably would drop this), but looking at some proposed names I really do think they're sufficiently less confusing than what we have now.

Editors talked again and refined names for copyExternalImageToTexture():

Old	New	Used in
GPUImageCopyTextureTagged	GPUCopyExternalImageDestination	copyExternalImageToTexture
GPUImageCopyExternalImage	GPUCopyExternalImageSource	copyExternalImageToTexture
GPUImageCopyExternalImageSource	GPUCopyExternalImageSourceData	member of ^ dictionary

I still have some thoughts bouncing around about possibly slightly better names for the other three, so I may post if I have ideas.

---

Assorted points, mostly from the editors' discussion:

• One good illustration of why the current names are worth fixing is GPUImageCopyExternalImage. This uses the word "image" twice to refer to entirely different concepts (slice of copy; HTML-spec image data).

• The fact that GPUCopyExternalImageDestination is the destination of copyExternalImageToTexture() is more important than the fact that it is Tagged or that it is a subtype of GPUTextureCopyOrigin. Both result from the semantics of the operation.

• What about GPUTexelCopy instead of GPUImageCopy?

  This is not a bad option. Calling them "texel copies" would be a nice, distinct name. On the other hand, all of these operations do interact directly with GPUTexture (as the source, destination, or both) and already have Texture in their names.

  One additional thought, GPUTexelCopyBufferLayout could end up being slightly confusing with "texel buffers", but probably fine with the extra word.

  For the moment we preferred "texture copies", but to work through this idea:
  It would allow us to use "Texture" as distinct from "Texel Copy" without being so confusing. So we could do this:
  GPUTexelCopyBuffer
GPUTexelCopyTexture (these are as you suggested I think)
  GPUTexelCopyLayout or GPUTexelCopyDataLayout (avoiding breaking the atomicity of the phrase "Texel Copy")

• Also GPUCopyExternalImageOrigin contains flipY which is weird for an "origin" that sounds just like a 2D location.

  Fair point, we were of the opinion that this probably wouldn't actually end up being confusing, but the names proposed above sidestep it by just using "Source" and "Destination". For this operation we're able to be more explicit about the direction of the copy, which we thought made it clearer.

• I don't think Origin makes this clearer, but maybe Desc[riptor]?

  We thought it was a little odd (though probably fine) that the copy would take two descriptors. We also are currently are very consistent about using the word "descriptor" only when creating objects, and I think that's a useful convention to keep.

  To work through this idea though, we'd potentially have names like:
  GPUTexelCopyTextureDescriptor
GPUTexelCopyBufferDescriptor
  ("Texel" to avoid "TextureCopyTexture".)
  This is not bad, but maybe just as good without "Descriptor"?

  (As mentioned I am still thinking about the of the one that still has "Origin" in it.)

• (Also "origin" in web specs is usually talking about e.g. domains and same-origin stuff)

  We already use "Origin" quite a lot (GPUOrigin3D, .origin in copies, etc.) so I don't really think avoiding it here improves that situation.

• On "image", IIRC Image in (at least) GL/Vulkan is generally the term for a mip-level of a Texture, which is why copies to and from textures are "image copies", because such copies are done per-mip-level. (A Texture is a structured set of Images)

  IIUC "image" is pretty well established as one 2d slice of a copy. We use it in this way in rowsPerImage, and GL (UNPACK_IMAGE_HEIGHT), Vulkan (bufferImageHeight), and Metal (destinationBytesPerImage) use it in the same way. (Vulkan also has VkImage, a different definition of "image". D3D12 is complicated but AFAICT doesn't use this term.)

  The copy-layout concept of "image" divides more finely than by mip-level - it also divides by z-slice (array layer of 2d, or slice of 3d). (I probably wish we'd called it "slice".) I think what you describe as an "image" is what we currently call a "subresource" in this spec, which for 2d is z-sliced but for 3d is not z-sliced.

  Initially GPUImageCopy was intended to refer to the same the meaning of "image" as rowsPerImage. However IMO this is unclear and in reality we one spec term "image" (see also Rename image->texel image, block row->texel block row #4689) and another totally separate term "image copy".

  A copy operation copies some texel data to or from a texture. This is a loop over Images (z), which is a loop over Rows (y), which is a loop over Texel Blocks (x). Why did we randomly name it after one of the intermediate concepts (Image)? It could just as well be called Row Copy. I'd rather either Texture Copy or Texel Copy, as they're more essential to the concept.