[RFC] Should we get rid of .$foo methods

[iwoplaza]

If we keep the initial/value properties as positional arguments:

// now
const foo = root.createBuffer(d.f32).$usage('mutable');
// potential future
const foo = root.createBuffer(d.f32, 0, { usage: ['mutable'] });

// now
const foo = root.createBuffer(d.f32).$name('foo').$usage('mutable');
// potential future
const foo = root.createBuffer(d.f32, 0, { name: 'foo', usage: ['mutable'] });

If we only keep the schema as the first positional argument:

// now
const buffer = root.createBuffer(d.f32, 0).$usage('mutable');
const size = tgpu.const(d.f32, 123);
const counter = tgpu.privateVar(d.u32, 0);

// potential future
const buffer = root.createBuffer(d.f32, { initial: 0, usage: ['mutable'] });
const size = tgpu.const(d.f32, { value: 123 });
const counter = tgpu.privateVar(d.u32, { initial: 0 });

[reczkok]

I feel like this would be easier for people to learn and more familiar for WebGPU/Vulkan/DX12 users
Also I feel like initial value not being optional would be a significant downgrade

[aleksanderkatan]

There is a potential ambiguity (maybe not idx, since this is a layout setting, but just to illustrate the idea):

// currently, this is valid because we strip extra props
const myStruct = d.struct({ idx: d.u32 });
const myInitialValue = { idx: 1, usage: ['readonly'] };
const myBuffer = root.createBuffer(myStruct, myInitialValue);

Cases where initial is present could be detected in runtime by object depth though. We can acquire schemaInstance by calling the schema.

function depth(o: unknown): number {
  if (o && typeof o === 'object') {
    return 1 + Math.max(...Object.values(o).map(depth))
  }
  return 1;
}

function whichApi(schemaInstance: object, options: object) {
  if (depth(schemaInstance) === depth(options)) {
    console.log("old");
  } else {
    console.log("new");
  }
}

whichApi({ p: { q: 0 } }, { p: { q: 1 } }); // old
whichApi({ p: { q: 0 } }, { initial: { p: { q: 1 } } }); // new

whichApi({ initial: 0 }, { initial: 1 }); // old
whichApi({ initial: 0 }, { initial: { initial: 1 } }); // new

I don't think we should decide on a clunky (forced initial if we want options) and inconsistent (different from typegpu/react) API just because of a breaking change, the latest release is 0.11.8 after all. Also, in this case the migration is really simple.

[aleksanderkatan]

On the other hand, I see how

const buf = root.createUniform(d.u32, { initial: 7 });

may feel more clunky than this

const buf = root.createUniform(d.u32, 7);

[iwoplaza]

We have the same problem with other name'able resources like tgpu.const and tgpu.privateVar:

// now
const size = tgpu.const(d.f32, 123).$name('size');
// potential future
const size = tgpu.const(d.f32, { value: 123, name: 'size' });

// now
const size = tgpu.const(d.f32, 123);
// potential future
const size = tgpu.const(d.f32, { value: 123 });

[aleksanderkatan]

With tgpu.const in particular, I don't think it's an issue. It requires a value, so the depth check would suffice (at least I think so).
But you're right that there are other APIs that are problematic, for example accessors. Users would need to rewrite way more code during migration that I initially thought.

[iwoplaza]

Apart from the migration burden, I feel like it would encourage people and AI to overzealously name things manually by the API design, instead of relying on auto-naming.

[deluksic]

Personally not a fan of $ in APIs in general, but I don't mind it that much.

[aleksanderkatan]

As a reminder, all the methods are:

• $usage(),
• $addFlags(),
• $as() $uses(),
• $idx(),
• $name().
  Do we consider getting rid of all of them? Can we do it with $idx?

[iwoplaza]

I don't think .$as() is an API, you were probably thinking of .as on buffers

[aleksanderkatan]

Sorry, I was listing them from memory. The fifth one is $uses()

[deluksic]

If I had to steelman builder API:

const bufferTemplate = root.createBuffer(d.f32);
const a = bufferTemplate.$usage('copy');
const b = bufferTemplate.$usage('vertex');

[deluksic]

But its not that different from:

const bufferType = d.f32;
const a = root.createBuffer(bufferType, ...);
const b = root.createBuffer(bufferType, ...);

[aleksanderkatan]

Edit: these are not equivalent at this moment ☹️

Currently, a and b will be the same buffer, this only narrows types.

Maybe this actually should create a new tgpu buffer?

[deluksic]

ah all the more reason to remove this API then