Weird GetBrushTexture behavior...exactly what is this command for?

Observe:

Graphics3D 400,300,16,2
t=CreateTexture(2,2)
mesh=CreateMesh()
surf=CreateSurface(mesh)
b=CreateBrush()
BrushTexture b,t
PaintSurface surf,b
b=GetSurfaceBrush(surf)
RuntimeError GetBrushTexture(b,0)+"<>"+t

GetBrushTexture returns a new texture handle. It says so in the docs, it's the same texture, only different handle.

Yup, that would seem to make brushtexture entirely worthless. However, I suspect something more is going on here.

In Blitz, if I'm not mistaken, when you apply a texture to an entity, and then free the texture, the entity remains textured. Perhaps someone should confirm this though as I'm not positive.

Anyhow, if true, this implies that the texture is copied when you apply it to an entity.

However, when you edit a texture, any entity using that texture takes on it's new appearance. This implies that the texture is NOT copied.

Either I'm mistaken, or Blitz is doing something funny with the textures. And this might be causing you to get unexpected results from this operation.

"GetBrushTexture returns a new texture handle. It says so in the docs, it's the same texture, only different handle."


It says no such thing. The docs, confusingly, state:

...

Returns the texture that is applied to the specified brush.

The optional index parameter allows you to specify which particular texture you'd like returning, if there are more than one textures applied to a brush.

You should release the texture returned by GetBrushTexture after use to prevent leaks! Use FreeTexture to do this.

To find out the name of the texture, use TextureName

...


This in particular is confusing:

"You should release the texture returned by GetBrushTexture after use to prevent leaks! Use FreeTexture to do this."

Why should returning the handle of the texture you assigned to the brush, and thus applied to the surface, then require you to use freetexture?


This is very confusing. What exactly is going on internally? Is the texture being COPIED to a NEW texture when you call this command? Does this happen every time you call the command on a specific entity, or jsut the first time? For what reason is the texture copied?

I thought the point of the brushtexture command was so that you could get the handle of the texture applied to a surface when you load a file that automatically applies the textures, or so that a third part library, like the YAL lightmapper for example, could get the texture applied to a speciifc surface of an entity passed to it by the user, so that it can then modify it, or get the color of the texels from it.

Why then would it need to copy anything?

Mark really needs to document these commands better. There's no point in adding new commands if he doesn't document them well enough so that people can make proper use of them.

The only thing I can think of is that it can be used to compare file names to known textures, but that seems like a roundabout way of doing things.

I completly agree. When I read the docs, I had exactly the same thoughts. Time for some testing, me thinks.

[EDIT]Ok, it doesn't seem to be copying the texture because even if I apply the newly acquired texture handle to another visible entity, the AvailVidMem() doesn't change. However, you can keep doing it over and over and over and the texture handle is always different, so it may be using system memory for all the extra handles. But since you can only free one texture, not both, it does kinda seem you're going to get memory leaks whether you like it or not. Or perhaps not if you only use it once per entity.[/EDIT]

GetSurfaceBrush() and GetEntityBrush() create a new brush based on the entity or brush data. This way you can free a brush or texture after applying it to an entity or surface, and then create a new brush to manipulate with GetSurfaceBrush() when you need it.

Should they be called
CopySurfaceBrush() and CopyEntityBrush()
instead of
GetSurfaceBrush() and GetEntityBrush() ?

Yes, those names makes more sense to me.

Humm so there is still no way to know what texture file was used for a determined entity / surface ?

You mean apart from the texturename command

http://www.blitzbasic.com/b3ddocs/command.php?name=texturename&ref=goto

This does allow some cool stuff.

Mesh save routines can now account for textures, finally!

You can go through the limbs and surfaces of a loaded mesh and apply shaders or properties.

If FileName(texturename$)="caulk" ClearSurface surf