1# Texture data completeness's handling in the Metal back-end 2 3The OpenGL spec allows a texture's images to be defined without consistent size and format through 4glTexImage*, glCopyImage* calls. The texture doesn't need to be complete when created. 5 6The OpenGL context checks the texture's images during draw calls. It considers the texture complete 7if the images are consistent in size and format. Then it uses the texture for rendering. 8 9Metal textures (i.e. MTLTexture) on the other hand require consistent defined images at all times. 10MTLTextures are always created complete. 11 12This is an overview of how the Metal back-end implements images' management for a texture to make 13sure it is GL spec conformant (TextureMtl): 141. Initially: 15 * no actual MTLTexture is created yet. 16 * glTexImage/glCopyImage(slice,level): 17 * a single image (`images[slice][level]`: 2D/3D MTLTexture no mipmap + single slice) is 18 created to store data for the texture at this level/slice. 19 * glTexSubImage/glCopyTexSubImage(slice,level): 20 * modifies the data of `images[slice][level]`; 212. If the texture is complete at Draw/generateMip/FBO attachment call: 22 * an actual MTLTexture object is created. We can call it "native" texture, i.e. the real texture 23 that will be consumed by Metal draw calls. 24 - `images[0][0]` --> copy to actual texture's slice 0, level 0. 25 - `images[0][1]` --> copy to actual texture's slice 0, level 1. 26 - `images[0][2]` --> copy to actual texture's slice 0, level 2. 27 - ... 28 * The images will be destroyed, then re-created to become texture views of the actual texture at 29 the specified level/slice. 30 - `images[0][0]` -> view of actual texture's slice 0, level 0. 31 - `images[0][1]` -> view of actual texture's slice 0, level 1. 32 - `images[0][2]` -> view of actual texture's slice 0, level 2. 33 - ... 343. After texture is complete: 35 * glTexSubImage/glCopyTexSubImage(slice,level): 36 * `images[slice][level]`'s content is modified, which means the actual texture's content at 37 respective slice & level is modified also. Since the former is a view of the latter at given 38 slice & level. 39 * glTexImage/glCopyImage(slice,level): 40 * If size != `images[slice][level]`.size(): 41 - Destroy the actual texture (the other views are kept intact), recreate 42 `images[slice][level]` as single image same as initial stage. The other views are kept 43 intact so that texture data at those slice & level can be reused later. 44 * else: 45 - behaves as glTexSubImage/glCopyTexSubImage(slice,level). 46