Panda Manual > BambooBasic Code Export

BambooBasic Code Export

File > Export As... with the .bam format writes your model as a BambooBasic include file. Everything is in the code - the vertices, the faces, the colours, the skeleton, the animation - so your program loads no model file. You Include it, call one function to set it up, and then pose it and draw it.

This page explains every choice in the export window and every function, array and constant the file gives you. The examples use a model named Panda; yours start with whatever name you give it.


When to use it

Use the code export when:

Use a .bb3d file instead when the model is big (thousands of vertices and many frames make a big source file that takes a while to build), or when you want to swap models without rebuilding your program.


The choices in the export window

Choose .bam - BambooBasic code under Format in the Export As window. Then:

Model nameUsed for the file name (Panda.bam) and as the start of every name in the code: Panda_Build(), PANDA_VERTS. Give each model you include a different name and they won't clash. Spaces and symbols become _; a name starting with a digit gets an M in front. The line under the name shows exactly what you'll get.
Animation Skeleton - the joints and their keys go in, and the code works the pose out from them while your program runs. Small, smooth (it blends between keys, not just frames) and your program can turn joints. Only for models with joints.

Baked frames - the animation worked out into frames (every vertex's place on every frame), like a .bb3d. Exactly what Panda plays, but much bigger, and nothing to turn. For models with joints or pose frames.

Both - both go in, and you choose in your program which to use.

None - just the model as it is (the rest pose).

Choices your model can't do are greyed out.
Default Model ControlsAdds a ready-made _Draw() that places, lights and draws the model in one call, with its light settings. Untick it if you want to draw the model your own way; everything else (posing, placing it in the world, the joint functions) is always there.
Data Readable - one line of code for each vertex, face, key and baked vertex (Panda_V(12, 0.25, -0.5, 0.1, 3)). Easy to read and change by hand, but slow to build for bigger models.

Packed - the numbers are packed three characters each into strings, unpacked when _Build() runs. Much smaller and much quicker to build (a 430-vertex model with 48 frames: 34 seconds readable, under 3 seconds packed), and still accurate to about a quarter-millionth of the model's size.

The window says how many lines the readable form would be, and picks Packed by itself above about 3000 - unless you've chosen yourself.

Click Export. Export Again (Ctrl+Shift+E) later writes the same file with the same choices, without asking.


Getting started

Put the .bam next to your program and include it. A complete program (desktop), with a model exported with a skeleton, a clip called Wave and Default Model Controls:

Import "BBRuntime64.decls"
Include "Panda.bam"

Function Main()
    b2dGraphics(900, 700, BBR_WINDOW_MODE_WVC)
    Panda_Build()                                   ; once, before anything else
    Panda_SetView(450.0, 350.0, 620.0, 0.5, 50.0)   ; screen centre, focal length, near, far
    Local start:Int = sysMillisecs()
    Local running:Int = True
    While running
        sysUpdateEvents()
        If inpIsKeyHit(VKEY_ESCAPE) Then running = False
        Local seconds:Double = (sysMillisecs() - start) / 1000.0
        Panda_PoseClip(PANDA_CLIP_WAVE, seconds)      ; pose it
        b2dCls()
        Panda_Draw(0.0, 0.0, 3.0, 0.0, 0.0, 0.0, 1.0)  ; x, y, z, yaw, pitch, roll, scale
        b2dFlip()
    Wend
    Return 0
EndFunction

(BBR_WINDOW_MODE_WVC and VKEY_ESCAPE come from BBR_INCLUDE.bam, which the examples include.) For a finished example see examples\Panda\PandaShow.bam and PandaShow_web.bam.

The top of every exported file lists what that file has - its functions, clips and joints - so you can always look there.


Names
ConstantWhat it is
PANDA_VERTSHow many vertices (the arrays go from 0 to this - 1).
PANDA_FACESHow many faces.
PANDA_COLOURSHow many colours.
PANDA_CLIPSHow many clips (with animation).
PANDA_JOINTS, PANDA_KEYSHow many joints and keys (with a skeleton).
PANDA_FRAMESHow many baked frames (with baked frames).
PANDA_CLIP_nameEach clip's number.
PANDA_J_nameEach joint's number.

Setting up: _Build and _Rest
Panda_Build()Call it once, before using anything else. It fills all the arrays (and unpacks packed data), clears any joint turns and puts the model in its rest pose.
Panda_Rest()Puts the model back in its rest pose (how it was modelled, with no animation) in Panda_X/Y/Z[]. With a skeleton, the joints go back to rest too.

Clips

A clip is a named run of frames with its own speed, as made in Panda's Clips window. A model with animation but no clips gets one called All covering every frame (at 12 frames a second). Clips loop: after the last frame the pose blends back to the first.

Panda_FindClip(name)A clip's number from its name, or -1 if there isn't one: c = Panda_FindClip("Wave"). (The PANDA_CLIP_... constants are quicker.)
Panda_ClipLength(clip)How long the clip lasts, in seconds (frames / speed).
Panda_ClipAt(clip, seconds)Where the clip is at a time: sets Panda_FrameA and Panda_FrameB (the frames either side) and Panda_FrameT (how far between them, 0 to 1). _PoseClip and _FrameClip use it; you only need it to know which frame you're on (to play a sound on a footstep, say).
Panda_ClipName[c], Panda_ClipStart[c], Panda_ClipCount[c], Panda_ClipFPS[c]Each clip's name, first frame, number of frames and frames per second.

The seconds you give is how long the clip has been playing. To play a clip once instead of looping, stop calling it when the time reaches Panda_ClipLength(clip) (or keep giving it just under that). To play it at another speed, multiply the seconds. To play it backwards, take the seconds away from the length.


Posing from the skeleton

With Skeleton (or Both), the joints and their keys are in the file and the pose is worked out as your program runs: each joint turns (and moves) the vertices that follow it, about its pivot, carried along by its parent joint. Between keys the turns are blended smoothly, exactly as Panda does it.

Panda_PoseClip(clip, seconds)Poses the model from a clip at a time (it loops), with any turns you've added. The posed vertices go into Panda_X/Y/Z[].
Panda_PoseFrame(frame)Poses it at one of Panda's frame numbers (as on Panda's frame slider). A fraction blends: 10.5 is halfway between frames 10 and 11.
Panda_PoseTurns()The rest pose with only your turns (no clip) - for a model you animate entirely from code.

Turning joints from your program

This is the code export's big trick, the way The Great POW Getaway poses its figures: a clip does the walking and your program turns the head to look at something - or your program does all the animating itself.

Panda_TurnJoint(joint, ax, ay, az)Sets a turn of your own for a joint, in degrees: ay about the up axis (turn left and right), ax about the side axis (nod), az about the front axis (tilt). It's applied about the joint's pivot, in its parent's directions, on top of whatever the clip does, and every child joint follows. It stays until you change it: set it again (or to 0, 0, 0) each frame as needed. Then call _PoseClip, _PoseFrame or _PoseTurns to see it.
Panda_ClearTurns()Takes every joint's turn away.
Panda_FindJoint(name)A joint's number from its name, or -1. (The PANDA_J_... constants are quicker.)
Panda_TurnX/Y/Z[j]The turns themselves, if you'd rather set or read them directly.

Positive turns follow the usual rule for BambooBasic's left-handed space as seen on screen: a positive ay on a model facing you turns its head towards your left, a positive ax tips its nose up. Try a small number and look.

; the head follows the mouse, on top of the Wave clip
Local yaw:Double = 0.0 - ToDouble(inpGetMouseX() - 450) / 450.0 * 50.0
Local pitch:Double = ToDouble(350 - inpGetMouseY()) / 350.0 * 25.0
Panda_TurnJoint(PANDA_J_HEAD, pitch, yaw, 0.0)
Panda_PoseClip(PANDA_CLIP_WAVE, seconds)

Where the joints are: attaching things

After posing, you can ask where any joint is - to put a sword in a hand, a hat on a head, a light on a helmet, or to aim a camera over a shoulder. The answers are in the model's own space (as in Panda); _PlacePoint and _ScreenPoint (below) then put them in the world or on the screen, placed the same way as the model.

Panda_JointPos(joint)Where the joint (its pivot) is now, as last posed, in Panda_rx, Panda_ry, Panda_rz.
Panda_JointPoint(joint, x, y, z)Where a point fixed to the joint is now, in Panda_rx/ry/rz. Give the point where it is in the rest pose - read it off Panda's views, or use a vertex's rest position (Panda_RV[v * 3], [v * 3 + 1], [v * 3 + 2]). Wherever the clip takes the joint, the point goes with it, turned the same way.
Panda_JointTurn(joint)The joint's turn now (in the model's space), as a rotation in Panda_qw, Panda_qx, Panda_qy, Panda_qz (a quaternion), to turn an attached object along with it. Panda_Rotate(qw, qx, qy, qz, x, y, z) turns a point by it into Panda_rx/ry/rz.
Panda_JointName[j], Panda_JP[j], Panda_JX/JY/JZ[j]Each joint's name, its parent's number (-1 for none) and its pivot in the rest pose.
; a glowing dot on the tip of the right paw
Panda_PoseClip(PANDA_CLIP_WAVE, seconds)
Panda_Draw(0.0, 0.0, 3.0, 0.0, 0.0, 0.0, 1.0)
Panda_JointPoint(PANDA_J_ARMR, -0.45, -0.55, -0.25)     ; the paw tip, in the rest pose
Panda_ScreenPoint(Panda_rx, Panda_ry, Panda_rz)          ; -> Panda_PX, Panda_PY
If Panda_PD >= 0.0 Then b2dDrawOval(ToInt(Panda_PX) - 4, ToInt(Panda_PY) - 4, 8, 8, True)

Posing from baked frames

With Baked frames (or Both), every frame's vertices are in the file, exactly as Panda shows them, and posing just blends between two frames - the same as b2dMeshAnimate does for a .bb3d. Joint turns and the joint functions don't apply to baked frames.

Panda_FrameClip(clip, seconds)Poses the model from the baked frames of a clip at a time (it loops), into Panda_X/Y/Z[].
Panda_ShowFrame(frame)Shows one baked frame.
Panda_ShowFrames(a, b, t)Blends between frames a and b (t 0 to 1).

Placing it in the world and on the screen

These are always in the file. The camera is at 0, 0, 0 looking along +z, with x to the right and y up - the same as the 3D in 2D examples. A model facing Panda's Front view faces this camera.

Panda_SetView(centreX, centreY, focal, zNear, zFar)The camera: the screen centre in pixels (half your screen size), the focal length (bigger zooms in; about your screen height is a normal view), and how near and far things can be drawn. Defaults: 400, 300, 500, 0.5, 100. Or set Panda_ViewX, Panda_ViewY, Panda_Focal, Panda_ZNear, Panda_ZFar.
Panda_Transform(x, y, z, yaw, pitch, roll, scale)Puts the posed model in the world: at x, y, z (z is the distance away from the camera), turned by yaw (about the up axis), pitch (about the side axis) and roll (about the front axis), in degrees and in that order, and scaled. The results go into Panda_CX/CY/CZ[].
Panda_Project()Turns Panda_CX/CY/CZ[] into screen positions: Panda_SX[], Panda_SY[] (whole pixels) and Panda_SD[] (the depth, 0 to 1, for the depth quads). A vertex nearer than zNear (or behind the camera) gets a depth of -1.
Panda_PlacePoint(x, y, z)One point in the model's space placed the same way as the last _Transform, into Panda_PX/PY/PZ.
Panda_ScreenPoint(x, y, z)The same, and onto the screen: Panda_PX, Panda_PY in pixels and Panda_PD the depth (-1 if it's behind the camera).

Default Model Controls: _Draw

Only with Default Model Controls ticked.

Panda_Draw(x, y, z, yaw, pitch, roll, scale)Places the model (_Transform), projects it (_Project) and draws its faces (_DrawFaces), each in its colour, lit by one light, with the depth quads so they overlap correctly. Faces with a corner behind the camera are skipped.
Panda_DrawFaces()Just the drawing part, for the last transform and projection - if you transform and project yourself.
Panda_LightX/Y/ZThe direction towards the light (it doesn't need to be length 1). Default 0.4, 0.7, -0.6: from the upper right, in front.
Panda_AmbientHow bright the side away from the light is, 0 to 1 (default 0.35).
Panda_CullBackTrue (default): faces turned away aren't drawn - faster, and right for closed models. False for open models (a flat plane, a leaf) so you see both sides.
Panda_TextureOnly for a model with a texture. Load the texture and put its handle here to draw the model textured: Panda_Texture = b2dLoadImage("Media/" + Panda_TextureFile). While it's 0 the faces are drawn in their colours. The texture is tinted by each face's colour and the light, so white faces show it as it is.

Drawing it your own way

Writing your own drawing is worth it: once you know how it works you can do anything with it - your own lighting, outlines, fog, shadows, effects. Everything you need is in plain arrays:

  1. Pose it (_PoseClip, _FrameClip, _Rest ...): the posed vertices are in Panda_X/Y/Z[].
  2. Place it with _Transform (or do your own maths on Panda_X/Y/Z).
  3. Project it with _Project (or your own projection).
  4. Draw each face f from its corners Panda_FV[f * 4 + 0..3] - a triangle repeats its last corner, so you can always draw four corners - with b2dDrawQuadDepth or b2dDrawImageQuadDepthUV, in its colour Panda_PR/PG/PB[Panda_FM[f]].

See 3D in 2D for how turning, projecting and the depth quads work, and the examples in examples\BambooRuntime\26 - 3D in 2D.


The data arrays
ArrayWhat's in it
Panda_X[v], Panda_Y[v], Panda_Z[v]The vertices as last posed (or the rest pose after _Build / _Rest).
Panda_RV[v * 3 + 0..2]The rest pose: x, y, z for each vertex. Never changes.
Panda_FN[f]Face f's corner count, 3 or 4.
Panda_FV[f * 4 + 0..3]Face f's vertices, in order round the face (anticlockwise seen from the front, by the right-hand rule in Panda's space). A triangle repeats its last corner.
Panda_FM[f]Face f's colour number.
Panda_PR[c], Panda_PG[c], Panda_PB[c]Colour c's red, green and blue, 0 to 255.
Panda_FUV[f * 8 + 0..7]With a texture: face f's texture coordinates, u and v for each of the 4 corners (0 to 1, from the top left of the texture).
Panda_TextureFileWith a texture: its file name, as saved by Panda.
Panda_VJ[v]With a skeleton: the joint vertex v follows (-1: none).
Panda_KF[k], Panda_KQ[k * 4 + 0..3], Panda_KM[k * 3 + 0..2]With a skeleton: the keys - frame, turn (w, x, y, z) and move (x, y, z) - joint by joint; Panda_JK0[j] is joint j's first key and Panda_JKN[j] how many it has.
Panda_BV[(frame * PANDA_VERTS + v) * 3 + 0..2]With baked frames: every vertex's place on every frame.
Panda_CX/CY/CZ[v], Panda_SX/SY/SD[v]The results of _Transform and _Project.

Tips and questions

Nothing shows. Check you called _Build() first, that _SetView's centre is half your screen size, and that the model is in front of the camera: z in _Draw must be more than zNear plus the model's size (try 3).

It's too big or too small. Change the scale (or z, or the focal length). Panda's Tools > Fit Model into the -1..1 Box makes a model about 2 units big before you export.

It faces away. Turn it with yaw = 180. Models made facing Panda's Front view face the camera at yaw 0.

Faces are missing on a flat or open model. Set Panda_CullBack = False.

Two models. Export each with its own name and include both: Hero.bam and Dog.bam give Hero_Draw and Dog_Draw. To draw one model several times (a herd of sheep), pose and draw it once for each, with its own place and time.

Building is slow. Export with Packed data. A readable file with thousands of lines takes the C++ compiler a long time; packed takes seconds.

The joint turn goes the wrong way. Use the opposite sign. Turns are in the parent joint's directions, so a turn on a forearm swings with the upper arm.

Will a new export break my program? Not if the names stay the same: re-export with the same model name, and your code keeps working. If you rename clips or joints in Panda, their constants change too.


< Files   |   Contents   |   Using models in your program >