B3DHardwareEngine is a render engine specifically designed to deal with HW accellerated implementations. The (currently only) difference to the generic render engine is that a HW accellerated engine automatically clips the virtual viewport specified by client. This is necessary since HW accellerated rasterizers can usually not render outside the actual display surface.

Note: If the viewport clipping proves to be efficient enough it might be promoted to the general render engine since there is no point in rendering outside the clipping rectangle.

	attributes
	clearDepthBuffer clearViewport: cullFace cullFace: fogType:density:rangeStart:rangeEnd:color: lineWidth lineWidth: pointSize pointSize: polygonMode polygonMode: swapInterval swapInterval:

	initialize
	bufferRect: destroy finish flush initialize initializeIn: initializeTarget reset swapBuffers

	morphic-support
	compositeTexture:at:translucent: provideOverlayCanvasDuring: restoreMorphicBackground:under: restoreMorphicForeground:above:

	primitives-renderer
	primCreateRendererSW:hw:x:y:w:h: primDestroyRenderer: primRender:getColorMasksInto: primRenderGetSurfaceDepth: primRenderGetSurfaceHandle: primRenderGetSurfaceHeight: primRenderGetSurfaceWidth: primRenderIsOverlay:

primitives-rendering

primClearDepthBuffer: primFinish: primFlush: primRender:clearViewport:with: primRender:getProperty: primRender:setBufferRectX:y:w:h: primRender:setFog:density:rangeStart:rangeEnd:color: primRender:setLights: primRender:setMaterial: primRender:setModelView:projection: primRender:setProperty:toInteger: primRender:setViewportX:y:w:h: primRenderVB:primitive:flags:texture:vertices:vertexCount:faces:faceCount: primSwapBuffers:

	primitives-textures
	primRender:allocateTexture:width:height: primRender:compositeTexture:x:y:w:h:translucent: primRender:destroyTexture: primRender:getTextureByteSex: primRender:getTextureDepth: primRender:getTextureSurface: primRender:texture:colorMasksInto: primRender:uploadTexture:from:

	private-rendering
	privateSetViewport: processVertexBuffer: renderPrimitive

	private-textures
	allocateOrRecycleTexture: allocateTexture: destroyTexture: displayForm:on: displayForm:on:from: textureHandleOf: uploadTexture:

	testing
	hasFrameBufferAccess isAccelerated isOverlayRenderer

	instance creation
	newIn: newOn:

	primitives
	primitiveSetVerboseLevel:

	testing
	isAvailable

	accessing	top
	target Return the rendering target
	target: Set the rendering target
	viewport:

	attributes	top
	clearDepthBuffer
	clearViewport:
	cullFace Return the current culling mode
	cullFace: Set backface culling. aSymbol must be either #cw, #ccw or nil.
	fogType:density:rangeStart:rangeEnd:color: Set the current fog mode. aSymbol must be either one of #none, #linear, #exp, or #exp2.
	lineWidth Return the current line width
	lineWidth: Set the current line width
	pointSize Return the current point size
	pointSize: Set the current point size
	polygonMode Return the current polygon mode (either #points, #lines or nil)
	polygonMode: Set the current polygon mode (either #points, #lines or nil)
	swapInterval Return the swap interval for the receiver (only in HW implementations). The swap interval is defined as: 0 - don't wait for vertical blank. 1 - swap only on vertical blank. n - swap only every n vertical blanks.
	swapInterval: Set the swap interval for the receiver (only in HW implementations). The swap interval is defined as: 0 - don't wait for vertical blank. 1 - swap only on vertical blank. n - swap only every n vertical blanks.

	initialize	top
	bufferRect: Set and validate the receiver's buffer rectangle
	destroy Utility - destroy all resources associated with any part of the engine
	finish Flush the pipeline and force changes to the output medium
	flush Flush the entire pipeline
	initialize
	initializeIn:
	initializeTarget See if the renderer exposes its rendering target for blts. If so, initialize the rendere's target with a form that we can use.
	reset
	swapBuffers Swap the receiver's buffers. Return true if successful, false otherwise

	morphic-support	top
	compositeTexture:at:translucent: Composite the given texture at aPoint into the receiver.
	provideOverlayCanvasDuring: Hand the sender a canvas that can be used for overlayed drawing. For now, we only provide one for renderers with direct frame buffer access. At some point I really want to revisit this scheme and use the overlay canvas for drawing the morphs in front but I don't have the time right now.
	restoreMorphicBackground:under: If necessary upload the contents of aRectangle from the rendering target into the engine.
	restoreMorphicForeground:above: If necessary upload the contents of aRectangle from the rendering target into the engine.

	primitives-renderer	top
	primCreateRendererSW:hw:x:y:w:h:
	primDestroyRenderer:
	primRender:getColorMasksInto: Primitive. If this renderer is associated with a surface that we can blt directly to, return the color masks for it.
	primRenderGetSurfaceDepth: Primitive. If this renderer is associated with a surface that we can blt directly to, return the surface height for it.
	primRenderGetSurfaceHandle: Primitive. If this renderer is associated with a surface that we can blt directly to, return the surface handle for it. This is usually the case if the receiver is rendering to some offscreen target device (OpenGL p-buffers; DirectDraw surfaces).
	primRenderGetSurfaceHeight: Primitive. If this renderer is associated with a surface that we can blt directly to, return the surface height for it.
	primRenderGetSurfaceWidth: Primitive. If this renderer is associated with a surface that we can blt directly to, return the surface width for it.
	primRenderIsOverlay: Primitive. Return true if the receiver is represented by a native window and Squeak cannot draw on top of it. On some systems (for instance Mac) it is possible to draw on top of the rendering target although it may be bound to a window. On others (like Windows and AFAIK most Unix systems) it is impossible to draw on top of a rendering context that is directly bound to a window.

	primitives-rendering	top
	primClearDepthBuffer:
	primFinish: Primitive. Finish all rendering operations on the receiver. Do not return before all rendering operations have taken effect.
	primFlush: Primitive. If any rendering operations are pending, force them to be executed. Do not wait until they have taken effect.
	primRender:clearViewport:with:
	primRender:getProperty: Primitive. Get some property.
	primRender:setBufferRectX:y:w:h:
	primRender:setFog:density:rangeStart:rangeEnd:color: Primitive. Set the current fog parameters.
	primRender:setLights:
	primRender:setMaterial:
	primRender:setModelView:projection:
	primRender:setProperty:toInteger: Primitive. Set some property.
	primRender:setViewportX:y:w:h:
	primRenderVB:primitive:flags:texture:vertices:vertexCount:faces:faceCount:
	primSwapBuffers: Primitive. Finish all rendering operations on the receiver. Do not return before all rendering operations have taken effect.

	primitives-textures	top
	primRender:allocateTexture:width:height: Primitive. Allocate a texture with the given dimensions. Note: The depth of the texture allocated may *not* match the specified values here.
	primRender:compositeTexture:x:y:w:h:translucent:
	primRender:destroyTexture: Primitive. Destroy the texture associated with the given handle.
	primRender:getTextureByteSex: Primitive. Return the byte sex of the texture (e.g., true for MSB false for LSB)
	primRender:getTextureDepth: Primitive. Return the actual depth of the texture with the given handle
	primRender:getTextureSurface: Primitive. Return the texture's surface handle for blitting from within Squeak. Fail if the surface cannot be accessed directly.
	primRender:texture:colorMasksInto: Primitive. Store the bit masks for each color into the given array.
	primRender:uploadTexture:from: Primitive. Upload the given form into the texture identified by handle.

	private-rendering	top
	privateSetViewport:
	processVertexBuffer: Process the given vertex buffer in this part of the engine.
	renderPrimitive Use underlying support for transform, clip and lighting if possible. This might actually be slower than the Squeak simulation but if the hardware does in fact support TL then it's going to be REALLY fast.

	private-textures	top
	allocateOrRecycleTexture: If a texture for the given one has already been allocated return it. If not, allocate a new texture.
	allocateTexture: Allocate a new texture for the given (Squeak internal) form. NOTE: The size/depth of the texture allocated can differ. Right now there's an implicit strategy in the primitive code for choosing the right tradeoff between speed and space. In the optimal case this will result in a texture which is 'good enough' for what we have but if that can't be achieved anything might come back. Also, textures might be subject to certain restrictions. Some graphics cards have minimum/maximum sizes of textures (some older even require squared textures) and this needs to be taken into account by the primitive. One thing that's currently not handled is if insufficient memory is encountered. This can happen if there's just not enough VRAM or AGP memory. A good idea would be to free up some of the already allocated textures but it's not quite sure if that'll do the trick and it would require flushing the renderer. Tricky.
	destroyTexture: Destroy the given external form
	displayForm:on: @@@ FIXME: Fix #displayOn: to use real color map if needed
	displayForm:on:from: @@@ FIXME: Fix #displayOn: to use real color map if needed
	textureHandleOf:
	uploadTexture:

	testing	top
	hasFrameBufferAccess Return true if we can access the receiver's frame buffer directly
	isAccelerated
	isOverlayRenderer Return true if the renderer is associated with a target that is always in front of Squeak's host window (such as when the renderer is bound to a separate OS window). If this is the case, then the renderer must be destroyed prior to actions that may result in somebody else attempting to draw in the occupied area. As an example, dragging a morph around that contains such an overlay renderer would not restore the original region of this renderer.

	accessing	top
	version B3DHardwareEngine version

	instance creation	top
	newIn:
	newOn: Accelerated engines want a buffer rectangle

	primitives	top
	primitiveSetVerboseLevel: Primitive. Set the reporting level for the engine. Values are 0 - print NO information ever 1 - print critical debug errors 2 - print debug warnings 3 - print extra information 4 - print extra warnings 5 - print information about primitive execution 10 - print information about each vertex and face

	testing	top
	isAvailable Return true if this engine is available (e.g., all of its parts are avaiable)