Basic 3D (Additional Instructions)

Hey! This program requires \_ASMLOAD. Download that too! *Warning!* As with any ASM program, this can probably mess up your system somehow, like by causing it to freeze if you provide bad data. Be careful and check that your arrays sizes and array ids are correct. This is a small set of commands that allows you to use the 3D hardware from SmileBASIC code. This is pretty much a proof of concept, but you could probably use it for something if you wanted. This allows you to render whatever models you can stuff into an array. This currently supports vertex colors only - it would be nice to add textures later, but it will require some trickery and hasn't been done yet. There also are a few built-in simple, low-poly shapes that you can use if you don't want to try and figure out how to create a new model. If you want to use this, it might help to reference https://www.problemkaputt.de/gbatek.htm#ds3dvideo[DS 3D Video] since that was what most of this is based on. * Orbits demo This is a demo showing example usage of the built-ins and (more importantly) how to use the very questionably designed `RMTX` command. Controls: - dPad - translate view (move camera) - touch screen - rotate view (rotate camera) - A button - exit program (and turn off 3D/restore console state) !https://youtube.com/watch?v=DlnMgoD8dFQ * Instruction summary ** RENDER Used to initialize and refresh the 3D display. ``` RENDER state ``` `RENDER 0` turns off the 3D hardware. `RENDER 1` turns on the 3D hardware and also serves as the buffer swap instruction. Additionally, this copies the console characters due to the regular console update not working for some unknown reason. I think this command also behaves as a `VSYNC`? This needs some actual testing, but it looks like it does. ** RMTX Handles various matrix operations. ``` RMTX type,form,x,y,z ``` |*Input|Description| |`type`|Controls the matrix mode. See https://www.problemkaputt.de/gbatek.htm#ds3dmatrixloadmultiply[DS 3D Matrix Load/Multiply] Essentially, use 0 to set the projection matrix, i.e. the camera, and 1 to set the position matrix, i.e. the one that moves all your models around. The other two are not yet useful in this system. | |`form`|Type of matrix to set or multiply by. The following options are provided: - 0-set projection - 1-set identity - 2-scale - 3-translate - 4-rotate Note that scale, rotate, and translate are all multiplicative operations, while projection and identity override the previous matrix setting. | |`x`,`y`,`z`|Usage varies with `form`.| This instruction handles matrix operations in a way that is somewhat compact, and mostly driven by implementation difficulty. *** projection form: - x=cotangent(FOV) - y=(n+f)/(n-f) - z=(2nf)/(n-f) Used to create the following projection matrix, based on GBATEK's example ``` [ .75x 0 0 0 ] [ 0 x 0 0 ] [ 0 0 y -1 ] [ 0 0 z 0 ] ``` Why is it like this? Because I didn't want to do any division in asm, so it is outsourced to the interpreter. Requires symmetry of lr, tb. See https://www.problemkaputt.de/gbatek.htm#ds3dmatrixexamplesprojection[DS 3D Matrix Examples (Projection)]. *** iden: Arguments are completely ignored but must be specified anyways because I didn't want to use the varargs function just for this. This sets the identity matrix. You've probably seen it before. *** scale Scaling corresponding to each axis. ``` [ x 0 0 0 ] [ 0 y 0 0 ] [ 0 0 z 0 ] [ 0 0 0 1 ] ``` *** translate Translation by x,y,z. ``` [ 1 0 0 0 ] [ 0 1 0 0 ] [ 0 0 1 0 ] [ x y z 1 ] ``` *** rotate - x=axis - y=cos(angle) - x=sin(angle) x controls which of 0=x,1=y,2=z to rotate around. y and z should be the values returned by the likes of `COS(angle)` and `SIN(angle)`. The reason is similar to the one for projection's weird form - I didn't want to create tables/functions for sin, cos, etc, so the user must provide those from PTC. Also, making everything three arguments works out nicer internally. ** RPOLY Writes polygons to the 3D engine buffers. ``` RPOLY type,array_index RPOLY -1,builtin_model ``` |*Input|Description| |`type`|The type of polygons provided. See https://www.problemkaputt.de/gbatek.htm#ds3dpolygondefinitionsbyvertices[DS 3D Polygon Definitions by Vertices]. If you provide -1, this function will instead use a built-in model.| |`array_index`|ID corresponding to array definition order. Example: ```sb DIM MOD0[100,1] 'id=0 DIM MOD1[100,2] 'id=1 DIM MOD2[200] 'id=2, etc. ``` This is done instead of array names because - You can dynamically change models - Array parsing was complicated (and worse due to not being swapable) The size of the array dimension(s) changes how the function operates. - 1D array: Interpreted as packed vertex data - 2D array, dim2=1: Interpreted as packed vertex data - 2D array, dim2=2: Interpreted as pairs of packed vertex data and vertex colors. | |`builtin_model`|Builtin models: ```none 0 - cube 1 - octahedron 2 - cone (hexagonal base) 3 - icosahedron 4 - cylinder (hexagonal prism) 5 - torus (this is also hexagonal) ```| ** RCOLOR Sets the vertex color for the next rendered shape. ``` RCOLOR color ``` |*Input|Description| |`color`|BGR 555 formatted color code.| Will apply to the entire model. Note that `RPOLY` with a colored array will override this - this is mostly intended for simplicity and use with the builtin models, which have no colors defined. * Misc design notes In keeping with the SmileBASIC standard of various systems having a certain prefix (like SP, BGM, etc.) every command here starts with an `R`. I would've liked to also design it so that arrays were the data type provided to `RPOLY` as that feels like what an "official" implementation would have done, but it had the issue of being both less functional and more complicated. Similarly, it might be better to allow the entire matrix to be controlled from `RMTX` for the sake of options, but this likely would be slower (setting up arrays would be slow in PTC) and probably even harder to understand (not that the current form is simple, but it's smaller at least). `RCOLOR` is pretty nice and easy to use. `RENDER` is a bit silly, but somewhat necessary due to how the 3D hardware works, and it's convenient for allowing the console to (partially) function normally. I may update this to support textures in the future, but it will have to remove some other functionality for memory reasons. Technically this version already removes the background color feature of the console already, but textures being added would break, at minimum, one screen's BG layers or sprites. This is probably a good trade, but I haven't implemented it yet and it might have other consequences too. * April Fools? The joke is that it's real (you may now laugh) Seriously, if it breaks please tell me, this took months and I would like it to know if it works on any systems other than mine. :) ASM source available at https://github.com/Minxrod/PTC-ASM.