PsychError SCREENMakeTexture(void)
{
size_t ix, iters;
PsychWindowRecordType *textureRecord;
PsychWindowRecordType *windowRecord;
PsychRectType rect;
psych_bool isImageMatrixBytes, isImageMatrixDoubles;
int numMatrixPlanes, xSize, ySize;
unsigned char *byteMatrix;
double *doubleMatrix;
GLuint *texturePointer;
GLubyte *texturePointer_b;
GLfloat *texturePointer_f;
double *rp, *gp, *bp, *ap;
GLubyte *rpb, *gpb, *bpb, *apb;
int usepoweroftwo, usefloatformat, assume_texorientation, textureShader;
double optimized_orientation;
psych_bool bigendian;
psych_bool planar_storage = FALSE;
// Detect endianity (byte-order) of machine:
ix=255;
rpb=(GLubyte*) &ix;
bigendian = ( *rpb == 255 ) ? FALSE : TRUE;
ix = 0; rpb = NULL;
if(PsychPrefStateGet_DebugMakeTexture()) //MARK #1
StoreNowTime();
//all subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
//Get the window structure for the onscreen window. It holds the onscreein GL context which we will need in the
//final step when we copy the texture from system RAM onto the screen.
PsychErrorExit(PsychCapNumInputArgs(7));
PsychErrorExit(PsychRequireNumInputArgs(2));
PsychErrorExit(PsychCapNumOutputArgs(1));
//get the window record from the window record argument and get info from the window record
PsychAllocInWindowRecordArg(kPsychUseDefaultArgPosition, TRUE, &windowRecord);
if((windowRecord->windowType!=kPsychDoubleBufferOnscreen) && (windowRecord->windowType!=kPsychSingleBufferOnscreen))
PsychErrorExitMsg(PsychError_user, "MakeTexture called on something else than a onscreen window");
// Get optional texture orientation flag:
assume_texorientation = 0;
PsychCopyInIntegerArg(6, FALSE, &assume_texorientation);
// Get optional texture shader handle:
textureShader = 0;
PsychCopyInIntegerArg(7, FALSE, &textureShader);
//get the argument and sanity check it.
isImageMatrixBytes=PsychAllocInUnsignedByteMatArg(2, kPsychArgAnything, &ySize, &xSize, &numMatrixPlanes, &byteMatrix);
isImageMatrixDoubles=PsychAllocInDoubleMatArg(2, kPsychArgAnything, &ySize, &xSize, &numMatrixPlanes, &doubleMatrix);
if(numMatrixPlanes > 4)
PsychErrorExitMsg(PsychError_inputMatrixIllegalDimensionSize, "Specified image matrix exceeds maximum depth of 4 layers");
if(ySize<1 || xSize <1)
PsychErrorExitMsg(PsychError_inputMatrixIllegalDimensionSize, "Specified image matrix must be at least 1 x 1 pixels in size");
if(! (isImageMatrixBytes || isImageMatrixDoubles))
PsychErrorExitMsg(PsychError_user, "Illegal argument type"); //not likely.
// Is this a special image matrix which is already pre-transposed to fit our optimal format?
if (assume_texorientation == 2) {
// Yes. Swap xSize and ySize to take this into account:
ix = (size_t) xSize;
xSize = ySize;
ySize = (int) ix;
ix = 0;
}
// Build defining rect for this texture:
PsychMakeRect(rect, 0, 0, xSize, ySize);
// Copy in texture preferred draw orientation hint. We default to zero degrees, if
// not provided.
// This parameter is not yet used. It is silently ignorerd for now...
optimized_orientation = 0;
PsychCopyInDoubleArg(3, FALSE, &optimized_orientation);
// Copy in special creation mode flag: It defaults to zero. If set to 1 then we
// always create a power-of-two GL_TEXTURE_2D texture. This is useful if one wants
// to create and use drifting gratings with no effort - texture wrapping is only available
// for GL_TEXTURE_2D, not for non-pot types. It is also useful if the texture is to be
// exported to external OpenGL code to simplify tex coords assignments.
usepoweroftwo=0;
PsychCopyInIntegerArg(4, FALSE, &usepoweroftwo);
// Check if size constraints are fullfilled for power-of-two mode:
if (usepoweroftwo & 1) {
for(ix = 1; ix < (size_t) xSize; ix*=2);
if (ix != (size_t) xSize) {
PsychErrorExitMsg(PsychError_inputMatrixIllegalDimensionSize, "Power-of-two texture requested but width of imageMatrix is not a power of two!");
}
for(ix = 1; ix < (size_t) ySize; ix*=2);
if (ix != (size_t) ySize) {
PsychErrorExitMsg(PsychError_inputMatrixIllegalDimensionSize, "Power-of-two texture requested but height of imageMatrix is not a power of two!");
}
}
// Check if creation of a floating point texture is requested? We default to non-floating point,
// standard 8 bpc textures if this parameter is not provided.
usefloatformat = 0;
PsychCopyInIntegerArg(5, FALSE, &usefloatformat);
if (usefloatformat<0 || usefloatformat>2) PsychErrorExitMsg(PsychError_user, "Invalid value for 'floatprecision' parameter provided! Valid values are 0 for 8bpc int, 1 for 16bpc float or 2 for 32bpc float.");
if (usefloatformat && !isImageMatrixDoubles) {
// Floating point texture requested. We only support this if our input is a double matrix, not
// for uint8 matrices - converting them to float precision would be just a waste of ressources
// without any benefit for precision.
PsychErrorExitMsg(PsychError_user, "Creation of a floating point precision texture requested, but uint8 matrix provided! Only double matrices are acceptable for this mode.");
}
//Create a texture record. Really just a window record adapted for textures.
PsychCreateWindowRecord(&textureRecord); //this also fills the window index field.
textureRecord->windowType=kPsychTexture;
// MK: We need to assign the screen number of the onscreen-window, so PsychCreateTexture()
// can query the size of the screen/onscreen-window...
textureRecord->screenNumber=windowRecord->screenNumber;
textureRecord->depth=32;
PsychCopyRect(textureRecord->rect, rect);
// Is texture storage in planar format explicitely requested by usercode? Do the gpu and its size
// constraints on textures support planar storage for this image?
// Can a proper planar -> interleaved remapping GLSL shader be generated and assigned for this texture?
if ((usepoweroftwo == 4) && (numMatrixPlanes > 1) && (windowRecord->gfxcaps & kPsychGfxCapFBO) && !(PsychPrefStateGet_ConserveVRAM() & kPsychDontCacheTextures) &&
(ySize * numMatrixPlanes <= windowRecord->maxTextureSize) && PsychAssignPlanarTextureShaders(textureRecord, windowRecord, numMatrixPlanes)) {
// Yes: Use the planar texture storage fast-path.
planar_storage = TRUE;
if (PsychPrefStateGet_Verbosity() > 6) printf("PTB-DEBUG: Using planar storage for %i layer texture of size %i x %i texels.\n", numMatrixPlanes, xSize, ySize);
}
else {
planar_storage = FALSE;
if (PsychPrefStateGet_Verbosity() > 7) printf("PTB-DEBUG: Using standard storage for %i layer texture of size %i x %i texels.\n", numMatrixPlanes, xSize, ySize);
}
//Allocate the texture memory and copy the MATLAB matrix into the texture memory.
if (usefloatformat || (planar_storage && !isImageMatrixBytes)) {
// Allocate a double for each color component and pixel:
textureRecord->textureMemorySizeBytes = sizeof(double) * (size_t) numMatrixPlanes * (size_t) xSize * (size_t) ySize;
}
else {
// Allocate one byte per color component and pixel:
textureRecord->textureMemorySizeBytes = (size_t) numMatrixPlanes * (size_t) xSize * (size_t) ySize;
}
// We allocate our own intermediate conversion buffer unless this is
// creation of a single-layer luminance8 integer texture from a single
// layer uint8 input matrix and client storage is disabled. In that case, we can use a zero-copy path:
if ((isImageMatrixBytes && (numMatrixPlanes == 1) && (!usefloatformat) && !(PsychPrefStateGet_ConserveVRAM() & kPsychDontCacheTextures)) ||
(isImageMatrixBytes && planar_storage)) {
// Zero copy path:
texturePointer = NULL;
}
else {
// Allocate memory:
if(PsychPrefStateGet_DebugMakeTexture()) StoreNowTime();
textureRecord->textureMemory = malloc(textureRecord->textureMemorySizeBytes);
if(PsychPrefStateGet_DebugMakeTexture()) StoreNowTime();
texturePointer = textureRecord->textureMemory;
}
// Does script explicitely request usage of a GL_TEXTURE_2D power-of-two texture?
if (usepoweroftwo & 1) {
// Enforce creation as a power-of-two texture:
textureRecord->texturetarget=GL_TEXTURE_2D;
}
// Now the conversion routines that convert Matlab/Octave matrices into memory
// buffers suitable for OpenGL:
if (planar_storage) {
// Planar texture storage, backed by a LUMINANCE texture container:
// Zero-Copy possible? Only for uint8 input -> uint8 output:
if (texturePointer == NULL) {
texturePointer = (GLuint*) byteMatrix;
textureRecord->textureMemory = texturePointer;
// Set size to zero, so PsychCreateTexture() does not free() our
// input buffer:
textureRecord->textureMemorySizeBytes = 0;
// This is always a LUMINANCE8 texture, backing our planar uint8 texture:
textureRecord->depth = 8 * numMatrixPlanes;
textureRecord->textureexternaltype = GL_UNSIGNED_BYTE;
textureRecord->textureexternalformat = GL_LUMINANCE;
textureRecord->textureinternalformat = GL_LUMINANCE8;
}
else {
// Some cast operation needed from double input format.
// We always cast from double to float, potentially with
// normalization and/or checking of value range.
textureRecord->textureexternalformat = GL_LUMINANCE;
if (usefloatformat) {
// Floating point or other high precision format:
textureRecord->depth = ((usefloatformat == 1) ? 16 : 32) * numMatrixPlanes;
textureRecord->textureexternaltype = GL_FLOAT;
textureRecord->textureinternalformat = (usefloatformat == 1) ? GL_LUMINANCE_FLOAT16_APPLE : GL_LUMINANCE_FLOAT32_APPLE;
// Override for missing floating point texture support: Try to use 16 bit fixed point signed normalized textures [-1.0 ; 1.0] resolved at 15 bits:
if ((usefloatformat == 1) && !(windowRecord->gfxcaps & kPsychGfxCapFPTex16)) textureRecord->textureinternalformat = GL_LUMINANCE16_SNORM;
// Perform copy with double -> float cast:
iters = (size_t) xSize * (size_t) ySize * (size_t) numMatrixPlanes;
texturePointer_f = (GLfloat*) texturePointer;
for(ix = 0; ix < iters; ix++) {
*(texturePointer_f++) = (GLfloat) *(doubleMatrix++);
}
iters = (size_t) xSize * (size_t) ySize;
}
else {
// 8 Bit format, but from double input matrix -> cast to uint8:
textureRecord->depth = 8 * numMatrixPlanes;
textureRecord->textureexternaltype = GL_UNSIGNED_BYTE;
textureRecord->textureinternalformat = GL_LUMINANCE8;
iters = (size_t) xSize * (size_t) ySize * (size_t) numMatrixPlanes;
texturePointer_b = (GLubyte*) texturePointer;
for(ix = 0; ix < iters; ix++) {
*(texturePointer_b++) = (GLubyte) *(doubleMatrix++);
}
iters = (size_t) xSize * (size_t) ySize;
}
}
}
else if (usefloatformat) {
// Conversion routines for HDR 16 bpc or 32 bpc textures -- Slow path.
// Our input is always double matrices...
iters = (size_t) xSize * (size_t) ySize;
// Our input buffer is always of GL_FLOAT precision:
textureRecord->textureexternaltype = GL_FLOAT;
texturePointer_f=(GLfloat*) texturePointer;
if(numMatrixPlanes==1) {
for(ix=0;ix<iters;ix++){
*(texturePointer_f++)= (GLfloat) *(doubleMatrix++);
}
textureRecord->depth=(usefloatformat==1) ? 16 : 32;
textureRecord->textureinternalformat = (usefloatformat==1) ? GL_LUMINANCE_FLOAT16_APPLE : GL_LUMINANCE_FLOAT32_APPLE;
textureRecord->textureexternalformat = GL_LUMINANCE;
// Override for missing floating point texture support: Try to use 16 bit fixed point signed normalized textures [-1.0 ; 1.0] resolved at 15 bits:
if ((usefloatformat==1) && !(windowRecord->gfxcaps & kPsychGfxCapFPTex16)) textureRecord->textureinternalformat = GL_LUMINANCE16_SNORM;
}
if(numMatrixPlanes==2) {
rp=(double*) ((size_t) doubleMatrix);
ap=(double*) ((size_t) rp + (size_t) iters * sizeof(double));
for(ix=0;ix<iters;ix++){
*(texturePointer_f++)= (GLfloat) *(rp++);
*(texturePointer_f++)= (GLfloat) *(ap++);
}
textureRecord->depth=(usefloatformat==1) ? 32 : 64;
textureRecord->textureinternalformat = (usefloatformat==1) ? GL_LUMINANCE_ALPHA_FLOAT16_APPLE : GL_LUMINANCE_ALPHA_FLOAT32_APPLE;
textureRecord->textureexternalformat = GL_LUMINANCE_ALPHA;
// Override for missing floating point texture support: Try to use 16 bit fixed point signed normalized textures [-1.0 ; 1.0] resolved at 15 bits:
if ((usefloatformat==1) && !(windowRecord->gfxcaps & kPsychGfxCapFPTex16)) textureRecord->textureinternalformat = GL_LUMINANCE16_ALPHA16_SNORM;
}
if(numMatrixPlanes==3) {
rp=(double*) ((size_t) doubleMatrix);
gp=(double*) ((size_t) rp + (size_t) iters * sizeof(double));
bp=(double*) ((size_t) gp + (size_t) iters * sizeof(double));
for(ix=0;ix<iters;ix++){
*(texturePointer_f++)= (GLfloat) *(rp++);
*(texturePointer_f++)= (GLfloat) *(gp++);
*(texturePointer_f++)= (GLfloat) *(bp++);
}
textureRecord->depth=(usefloatformat==1) ? 48 : 96;
textureRecord->textureinternalformat = (usefloatformat==1) ? GL_RGB_FLOAT16_APPLE : GL_RGB_FLOAT32_APPLE;
textureRecord->textureexternalformat = GL_RGB;
// Override for missing floating point texture support: Try to use 16 bit fixed point signed normalized textures [-1.0 ; 1.0] resolved at 15 bits:
if ((usefloatformat==1) && !(windowRecord->gfxcaps & kPsychGfxCapFPTex16)) textureRecord->textureinternalformat = GL_RGB16_SNORM;
}
if(numMatrixPlanes==4) {
rp=(double*) ((size_t) doubleMatrix);
gp=(double*) ((size_t) rp + (size_t) iters * sizeof(double));
bp=(double*) ((size_t) gp + (size_t) iters * sizeof(double));
ap=(double*) ((size_t) bp + (size_t) iters * sizeof(double));
for(ix=0;ix<iters;ix++){
*(texturePointer_f++)= (GLfloat) *(rp++);
*(texturePointer_f++)= (GLfloat) *(gp++);
*(texturePointer_f++)= (GLfloat) *(bp++);
*(texturePointer_f++)= (GLfloat) *(ap++);
}
textureRecord->depth=(usefloatformat==1) ? 64 : 128;
textureRecord->textureinternalformat = (usefloatformat==1) ? GL_RGBA_FLOAT16_APPLE : GL_RGBA_FLOAT32_APPLE;
textureRecord->textureexternalformat = GL_RGBA;
// Override for missing floating point texture support: Try to use 16 bit fixed point signed normalized textures [-1.0 ; 1.0] resolved at 15 bits:
if ((usefloatformat==1) && !(windowRecord->gfxcaps & kPsychGfxCapFPTex16)) textureRecord->textureinternalformat = GL_RGBA16_SNORM;
}
// End of HDR conversion code...
}
else {
// Standard LDR texture 8 bpc conversion routines -- Fast path.
iters = (size_t) xSize * (size_t) ySize;
// Improved implementation: Takes 13 ms on a 800x800 texture...
if(isImageMatrixDoubles && numMatrixPlanes==1){
texturePointer_b=(GLubyte*) texturePointer;
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= (GLubyte) *(doubleMatrix++);
}
textureRecord->depth=8;
}
// Improved version: Takes 3 ms on a 800x800 texture...
// NB: Implementing memcpy manually by a for-loop takes 10 ms! This is a huge difference.
// -> That's because memcpy on MacOS-X is implemented with hand-coded, highly tuned Assembler code for PowerPC.
// -> It's always wise to use system-routines if available, instead of coding it by yourself!
if(isImageMatrixBytes && numMatrixPlanes==1) {
if (texturePointer) {
// Need to do a copy. Use optimized memcpy():
memcpy((void*) texturePointer, (void*) byteMatrix, iters);
//texturePointer_b=(GLubyte*) texturePointer;
//for(ix=0;ix<iters;ix++){
// *(texturePointer_b++) = *(byteMatrix++);
//}
}
else {
// Zero-Copy path. Just pass a pointer to our input matrix:
texturePointer = (GLuint*) byteMatrix;
textureRecord->textureMemory = texturePointer;
// Set size to zero, so PsychCreateTexture() does not free() our
// input buffer:
textureRecord->textureMemorySizeBytes = 0;
}
textureRecord->depth=8;
}
// New version: Takes 33 ms on a 800x800 texture...
if(isImageMatrixDoubles && numMatrixPlanes==2){
texturePointer_b=(GLubyte*) texturePointer;
rp=(double*) ((size_t) doubleMatrix);
ap=(double*) ((size_t) rp + (size_t) iters * sizeof(double));
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= (GLubyte) *(rp++);
*(texturePointer_b++)= (GLubyte) *(ap++);
}
textureRecord->depth=16;
}
// New version: Takes 20 ms on a 800x800 texture...
if(isImageMatrixBytes && numMatrixPlanes==2){
texturePointer_b=(GLubyte*) texturePointer;
rpb=(GLubyte*) ((size_t) byteMatrix);
apb=(GLubyte*) ((size_t) rpb + (size_t) iters);
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= *(rpb++);
*(texturePointer_b++)= *(apb++);
}
textureRecord->depth=16;
}
// Improved version: Takes 43 ms on a 800x800 texture...
if(isImageMatrixDoubles && numMatrixPlanes==3){
texturePointer_b=(GLubyte*) texturePointer;
rp=(double*) ((size_t) doubleMatrix);
gp=(double*) ((size_t) rp + (size_t) iters * sizeof(double));
bp=(double*) ((size_t) gp + (size_t) iters * sizeof(double));
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= (GLubyte) *(rp++);
*(texturePointer_b++)= (GLubyte) *(gp++);
*(texturePointer_b++)= (GLubyte) *(bp++);
}
textureRecord->depth=24;
}
// Improved version: Takes 25 ms on a 800x800 texture...
if(isImageMatrixBytes && numMatrixPlanes==3){
texturePointer_b=(GLubyte*) texturePointer;
rpb=(GLubyte*) ((size_t) byteMatrix);
gpb=(GLubyte*) ((size_t) rpb + (size_t) iters);
bpb=(GLubyte*) ((size_t) gpb + (size_t) iters);
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= *(rpb++);
*(texturePointer_b++)= *(gpb++);
*(texturePointer_b++)= *(bpb++);
}
textureRecord->depth=24;
}
// Improved version: Takes 55 ms on a 800x800 texture...
if(isImageMatrixDoubles && numMatrixPlanes==4){
texturePointer_b=(GLubyte*) texturePointer;
rp=(double*) ((size_t) doubleMatrix);
gp=(double*) ((size_t) rp + (size_t) iters * sizeof(double));
bp=(double*) ((size_t) gp + (size_t) iters * sizeof(double));
ap=(double*) ((size_t) bp + (size_t) iters * sizeof(double));
if (bigendian) {
// Code for big-endian machines like PowerPC:
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= (GLubyte) *(ap++);
*(texturePointer_b++)= (GLubyte) *(rp++);
*(texturePointer_b++)= (GLubyte) *(gp++);
*(texturePointer_b++)= (GLubyte) *(bp++);
}
}
else {
// Code for little-endian machines like Intel Pentium:
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= (GLubyte) *(bp++);
*(texturePointer_b++)= (GLubyte) *(gp++);
*(texturePointer_b++)= (GLubyte) *(rp++);
*(texturePointer_b++)= (GLubyte) *(ap++);
}
}
textureRecord->depth=32;
}
// Improved version: Takes 33 ms on a 800x800 texture...
if(isImageMatrixBytes && numMatrixPlanes==4){
texturePointer_b=(GLubyte*) texturePointer;
rpb=(GLubyte*) ((size_t) byteMatrix);
gpb=(GLubyte*) ((size_t) rpb + (size_t) iters);
bpb=(GLubyte*) ((size_t) gpb + (size_t) iters);
apb=(GLubyte*) ((size_t) bpb + (size_t) iters);
if (bigendian) {
// Code for big-endian machines like PowerPC:
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= *(apb++);
*(texturePointer_b++)= *(rpb++);
*(texturePointer_b++)= *(gpb++);
*(texturePointer_b++)= *(bpb++);
}
}
else {
// Code for little-endian machines like Intel Pentium:
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= *(bpb++);
*(texturePointer_b++)= *(gpb++);
*(texturePointer_b++)= *(rpb++);
*(texturePointer_b++)= *(apb++);
}
}
textureRecord->depth=32;
}
} // End of 8 bpc texture conversion code (fast-path for LDR textures)
// Override for missing floating point texture support?
if ((usefloatformat==1) && !(windowRecord->gfxcaps & kPsychGfxCapFPTex16)) {
// Override enabled. Instead of a 16bpc float texture with 11 bit linear precision in the
// range [-1.0 ; 1.0], we use a 16 bit signed normalized texture with a normalized value
// range of [-1.0; 1.0], encoded with 1 bit sign and 15 bit magnitude. These textures have
// an effective linear precision of 15 bits - better than 16 bpc float - but they are restricted
// to a value range of [-1.0 ; 1.0], as opposed to 16 bpc float textures. Tell user about this
// replacement at high verbosity levels:
if (PsychPrefStateGet_Verbosity() > 4)
printf("PTB-INFO:MakeTexture: Code requested 16 bpc float texture, but this is unsupported. Trying to use 16 bit snorm texture instead.\n");
// Signed normalized textures supported? Otherwise we bail...
if (!(windowRecord->gfxcaps & kPsychGfxCapSNTex16)) {
printf("PTB-ERROR:MakeTexture: Code requested 16 bpc floating point texture, but this is unsupported by this graphics card.\n");
printf("PTB-ERROR:MakeTexture: Tried to use 16 bit snorm texture instead, but failed as this is unsupported as well.\n");
PsychErrorExitMsg(PsychError_user, "Creation of 15 bit linear precision signed normalized texture failed. Not supported by your graphics hardware!");
}
// Check value range of pixels. This will not work for out of [-1; 1] range values.
texturePointer_f=(GLfloat*) texturePointer;
iters = iters * (size_t) numMatrixPlanes;
for (ix=0; ix<iters; ix++, texturePointer_f++) {
if(fabs((double) *texturePointer_f) > 1.0) {
// Game over!
printf("PTB-ERROR:MakeTexture: Code requested 16 bpc floating point texture, but this is unsupported by this graphics card.\n");
printf("PTB-ERROR:MakeTexture: Tried to use 16 bit snorm texture instead, but failed because some pixels are outside the\n");
printf("PTB-ERROR:MakeTexture: representable range -1.0 to 1.0 for this texture type. Change your code or update your graphics hardware.\n");
PsychErrorExitMsg(PsychError_user, "Creation of 15 bit linear precision signed normalized texture failed due to out of [-1 ; +1] range pixel values!");
}
}
}
// This is a special workaround for bugs in FLOAT16 texture creation on Mac OS/X 10.4.x and 10.5.x.
// The OpenGL fails to properly flush very small values (< 1e-9) to zero when creating a FLOAT16
// type texture. Instead it seems to initialize with trash data, corrupting the texture.
// Therefore, if FLOAT16 texture creation is requested, we loop over the whole input buffer and
// set all values with magnitude smaller than 1e-9 to zero. Better safe than sorry...
if ((usefloatformat==1) && (windowRecord->gfxcaps & kPsychGfxCapFPTex16)) {
texturePointer_f=(GLfloat*) texturePointer;
iters = iters * (size_t) numMatrixPlanes;
for(ix=0; ix<iters; ix++, texturePointer_f++) if(fabs((double) *texturePointer_f) < 1e-9) { *texturePointer_f = 0.0; }
}
// The memory buffer now contains our texture data in a format ready to submit to OpenGL.
// Assign parent window and copy its inheritable properties:
PsychAssignParentWindow(textureRecord, windowRecord);
// Texture orientation is zero aka transposed aka non-renderswapped.
textureRecord->textureOrientation = ((assume_texorientation != 2) && (assume_texorientation != 3)) ? 0 : 2;
// This is our best guess about the number of image channels:
textureRecord->nrchannels = numMatrixPlanes;
if (planar_storage) {
// Setup special rect to fake PsychCreateTexture() into creating a luminance
// texture numMatrixPlanes times the height (in rows) of the texture, to store the
// numMatrixPlanes layers concatenated to each other.
if (textureRecord->textureOrientation == 0) {
// Normal case: Transposed storage.
PsychMakeRect(&(textureRecord->rect[0]), 0, 0, xSize * numMatrixPlanes, ySize);
}
else {
// Special case: Non-transposed or isotropic storage:
PsychMakeRect(&(textureRecord->rect[0]), 0, 0, xSize, ySize * numMatrixPlanes);
}
// Create planar texture:
PsychCreateTexture(textureRecord);
// Restore rect and clientrect of texture to effective size:
PsychMakeRect(&(textureRecord->rect[0]), 0, 0, xSize, ySize);
PsychCopyRect(textureRecord->clientrect, textureRecord->rect);
textureRecord->specialflags = kPsychPlanarTexture;
}
else {
// Let's create and bind a new texture object and fill it with our new texture data.
PsychCreateTexture(textureRecord);
// Assign GLSL filter-/lookup-shaders if needed:
PsychAssignHighPrecisionTextureShaders(textureRecord, windowRecord, usefloatformat, (usepoweroftwo & 2) ? 1 : 0);
}
// User specified override shader for this texture provided? This is useful for
// basic image processing and procedural texture shading:
if (textureShader!=0) {
// Assign provided shader as filtershader to this texture: We negate it so
// that the texture blitter routines know this is a custom shader, not our
// built in filter shader:
textureRecord->textureFilterShader = -1 * textureShader;
}
// Texture ready. Mark it valid and return handle to userspace:
PsychSetWindowRecordValid(textureRecord);
PsychCopyOutDoubleArg(1, FALSE, textureRecord->windowIndex);
// Swapping the texture to upright orientation requested?
if (assume_texorientation == 1) {
// Transform sourceRecord source texture into a normalized, upright texture if it isn't already in
// that format. We require this standard orientation for simplified shader design.
PsychSetShader(windowRecord, 0);
PsychNormalizeTextureOrientation(textureRecord);
}
// Shall the texture be finally declared "normally oriented"?
// This is either due to explicit renderswapping if assume_textureorientation == 1,
// or because it was already pretransposed in Matlab/Octave if assume_textureorientation == 2,
// or because user space tells us the texture is isotropic if assume_textureorientation == 3.
if (assume_texorientation > 0) {
// Yes. Label it as such:
textureRecord->textureOrientation = 2;
}
if(PsychPrefStateGet_DebugMakeTexture()) //MARK #4
StoreNowTime();
return(PsychError_none);
}
PsychError SCREENMakeTexture(void)
{
int ix;
PsychWindowRecordType *textureRecord;
PsychWindowRecordType *windowRecord;
PsychRectType rect;
Boolean isImageMatrixBytes, isImageMatrixDoubles;
int numMatrixPlanes, xSize, ySize, iters;
unsigned char *byteMatrix;
double *doubleMatrix;
GLuint *texturePointer;
GLubyte *texturePointer_b;
GLfloat *texturePointer_f;
double *rp, *gp, *bp, *ap;
GLubyte *rpb, *gpb, *bpb, *apb;
int usepoweroftwo, usefloatformat, assume_texorientation, textureShader;
double optimized_orientation;
Boolean bigendian;
// Detect endianity (byte-order) of machine:
ix=255;
rpb=(GLubyte*) &ix;
bigendian = ( *rpb == 255 ) ? FALSE : TRUE;
ix = 0; rpb = NULL;
if(PsychPrefStateGet_DebugMakeTexture()) //MARK #1
StoreNowTime();
//all subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
//Get the window structure for the onscreen window. It holds the onscreein GL context which we will need in the
//final step when we copy the texture from system RAM onto the screen.
PsychErrorExit(PsychCapNumInputArgs(7));
PsychErrorExit(PsychRequireNumInputArgs(2));
PsychErrorExit(PsychCapNumOutputArgs(1));
//get the window record from the window record argument and get info from the window record
PsychAllocInWindowRecordArg(kPsychUseDefaultArgPosition, TRUE, &windowRecord);
if((windowRecord->windowType!=kPsychDoubleBufferOnscreen) && (windowRecord->windowType!=kPsychSingleBufferOnscreen))
PsychErrorExitMsg(PsychError_user, "MakeTexture called on something else than a onscreen window");
// Get optional texture orientation flag:
assume_texorientation = 0;
PsychCopyInIntegerArg(6, FALSE, &assume_texorientation);
// Get optional texture shader handle:
textureShader = 0;
PsychCopyInIntegerArg(7, FALSE, &textureShader);
//get the argument and sanity check it.
isImageMatrixBytes=PsychAllocInUnsignedByteMatArg(2, kPsychArgAnything, &ySize, &xSize, &numMatrixPlanes, &byteMatrix);
isImageMatrixDoubles=PsychAllocInDoubleMatArg(2, kPsychArgAnything, &ySize, &xSize, &numMatrixPlanes, &doubleMatrix);
if(numMatrixPlanes > 4)
PsychErrorExitMsg(PsychError_inputMatrixIllegalDimensionSize, "Specified image matrix exceeds maximum depth of 4 layers");
if(ySize<1 || xSize <1)
PsychErrorExitMsg(PsychError_inputMatrixIllegalDimensionSize, "Specified image matrix must be at least 1 x 1 pixels in size");
if(! (isImageMatrixBytes || isImageMatrixDoubles))
PsychErrorExitMsg(PsychError_user, "Illegal argument type"); //not likely.
// Is this a special image matrix which is already pre-transposed to fit our optimal format?
if (assume_texorientation == 2) {
// Yes. Swap xSize and ySize to take this into account:
ix = xSize;
xSize = ySize;
ySize = ix;
ix = 0;
}
// Build defining rect for this texture:
PsychMakeRect(rect, 0, 0, xSize, ySize);
// Copy in texture preferred draw orientation hint. We default to zero degrees, if
// not provided.
// This parameter is not yet used. It is silently ignorerd for now...
optimized_orientation = 0;
PsychCopyInDoubleArg(3, FALSE, &optimized_orientation);
// Copy in special creation mode flag: It defaults to zero. If set to 1 then we
// always create a power-of-two GL_TEXTURE_2D texture. This is useful if one wants
// to create and use drifting gratings with no effort - texture wrapping is only available
// for GL_TEXTURE_2D, not for non-pot types. It is also useful if the texture is to be
// exported to external OpenGL code to simplify tex coords assignments.
usepoweroftwo=0;
PsychCopyInIntegerArg(4, FALSE, &usepoweroftwo);
// Check if size constraints are fullfilled for power-of-two mode:
if (usepoweroftwo & 1) {
for(ix = 1; ix < xSize; ix*=2);
if (ix!=xSize) {
PsychErrorExitMsg(PsychError_inputMatrixIllegalDimensionSize, "Power-of-two texture requested but width of imageMatrix is not a power of two!");
}
for(ix = 1; ix < ySize; ix*=2);
if (ix!=ySize) {
PsychErrorExitMsg(PsychError_inputMatrixIllegalDimensionSize, "Power-of-two texture requested but height of imageMatrix is not a power of two!");
}
}
// Check if creation of a floating point texture is requested? We default to non-floating point,
// standard 8 bpc textures if this parameter is not provided.
usefloatformat = 0;
PsychCopyInIntegerArg(5, FALSE, &usefloatformat);
if (usefloatformat<0 || usefloatformat>2) PsychErrorExitMsg(PsychError_user, "Invalid value for 'floatprecision' parameter provided! Valid values are 0 for 8bpc int, 1 for 16bpc float or 2 for 32bpc float.");
if (usefloatformat && !isImageMatrixDoubles) {
// Floating point texture requested. We only support this if our input is a double matrix, not
// for uint8 matrices - converting them to float precision would be just a waste of ressources
// without any benefit for precision.
PsychErrorExitMsg(PsychError_user, "Creation of a floating point precision texture requested, but uint8 matrix provided! Only double matrices are acceptable for this mode.");
}
//Create a texture record. Really just a window record adapted for textures.
PsychCreateWindowRecord(&textureRecord); //this also fills the window index field.
textureRecord->windowType=kPsychTexture;
// MK: We need to assign the screen number of the onscreen-window, so PsychCreateTexture()
// can query the size of the screen/onscreen-window...
textureRecord->screenNumber=windowRecord->screenNumber;
textureRecord->depth=32;
PsychCopyRect(textureRecord->rect, rect);
//Allocate the texture memory and copy the MATLAB matrix into the texture memory.
// MK: We only allocate the amount really needed for given format, aka numMatrixPlanes - Bytes per pixel.
if (usefloatformat) {
// Allocate a double for each color component and pixel:
textureRecord->textureMemorySizeBytes= sizeof(double) * numMatrixPlanes * xSize * ySize;
}
else {
// Allocate one byte per color component and pixel:
textureRecord->textureMemorySizeBytes= numMatrixPlanes * xSize * ySize;
}
// MK: Allocate memory page-aligned... -> Helps Apple texture range extensions et al.
if(PsychPrefStateGet_DebugMakeTexture()) //MARK #2
StoreNowTime();
textureRecord->textureMemory=malloc(textureRecord->textureMemorySizeBytes);
if(PsychPrefStateGet_DebugMakeTexture()) //MARK #3
StoreNowTime();
texturePointer=textureRecord->textureMemory;
// Does script explicitely request usage of a GL_TEXTURE_2D power-of-two texture?
if (usepoweroftwo & 1) {
// Enforce creation as a power-of-two texture:
textureRecord->texturetarget=GL_TEXTURE_2D;
}
// Now the conversion routines that convert Matlab/Octave matrices into memory
// buffers suitable for OpenGL:
if (usefloatformat) {
// Conversion routines for HDR 16 bpc or 32 bpc textures -- Slow path.
// Our input is always double matrices...
iters = xSize * ySize;
// Our input buffer is always of GL_FLOAT precision:
textureRecord->textureexternaltype = GL_FLOAT;
texturePointer_f=(GLfloat*) texturePointer;
if(numMatrixPlanes==1) {
for(ix=0;ix<iters;ix++){
*(texturePointer_f++)= (GLfloat) *(doubleMatrix++);
}
textureRecord->depth=(usefloatformat==1) ? 16 : 32;
textureRecord->textureinternalformat = (usefloatformat==1) ? GL_LUMINANCE_FLOAT16_APPLE : GL_LUMINANCE_FLOAT32_APPLE;
textureRecord->textureexternalformat = GL_LUMINANCE;
}
if(numMatrixPlanes==2) {
rp=(double*) ((psych_uint64) doubleMatrix);
ap=(double*) ((psych_uint64) doubleMatrix + (psych_uint64) iters*sizeof(double));
for(ix=0;ix<iters;ix++){
*(texturePointer_f++)= (GLfloat) *(rp++);
*(texturePointer_f++)= (GLfloat) *(ap++);
}
textureRecord->depth=(usefloatformat==1) ? 32 : 64;
textureRecord->textureinternalformat = (usefloatformat==1) ? GL_LUMINANCE_ALPHA_FLOAT16_APPLE : GL_LUMINANCE_ALPHA_FLOAT32_APPLE;
textureRecord->textureexternalformat = GL_LUMINANCE_ALPHA;
}
if(numMatrixPlanes==3) {
rp=(double*) ((psych_uint64) doubleMatrix);
gp=(double*) ((psych_uint64) doubleMatrix + (psych_uint64) iters*sizeof(double));
bp=(double*) ((psych_uint64) gp + (psych_uint64) iters*sizeof(double));
for(ix=0;ix<iters;ix++){
*(texturePointer_f++)= (GLfloat) *(rp++);
*(texturePointer_f++)= (GLfloat) *(gp++);
*(texturePointer_f++)= (GLfloat) *(bp++);
}
textureRecord->depth=(usefloatformat==1) ? 48 : 96;
textureRecord->textureinternalformat = (usefloatformat==1) ? GL_RGB_FLOAT16_APPLE : GL_RGB_FLOAT32_APPLE;
textureRecord->textureexternalformat = GL_RGB;
}
if(numMatrixPlanes==4) {
rp=(double*) ((psych_uint64) doubleMatrix);
gp=(double*) ((psych_uint64) doubleMatrix + (psych_uint64) iters*sizeof(double));
bp=(double*) ((psych_uint64) gp + (psych_uint64) iters*sizeof(double));
ap=(double*) ((psych_uint64) bp + (psych_uint64) iters*sizeof(double));
for(ix=0;ix<iters;ix++){
*(texturePointer_f++)= (GLfloat) *(rp++);
*(texturePointer_f++)= (GLfloat) *(gp++);
*(texturePointer_f++)= (GLfloat) *(bp++);
*(texturePointer_f++)= (GLfloat) *(ap++);
}
textureRecord->depth=(usefloatformat==1) ? 64 : 128;
textureRecord->textureinternalformat = (usefloatformat==1) ? GL_RGBA_FLOAT16_APPLE : GL_RGBA_FLOAT32_APPLE;
textureRecord->textureexternalformat = GL_RGBA;
}
// This is a special workaround for bugs in FLOAT16 texture creation on Mac OS/X 10.4.x and 10.5.x.
// The OpenGL fails to properly flush very small values (< 1e-9) to zero when creating a FLOAT16
// type texture. Instead it seems to initialize with trash data, corrupting the texture.
// Therefore, if FLOAT16 texture creation is requested, we loop over the whole input buffer and
// set all values with magnitude smaller than 1e-9 to zero. Better safe than sorry...
if(usefloatformat==1) {
texturePointer_f=(GLfloat*) texturePointer;
iters = iters * numMatrixPlanes;
for(ix=0; ix<iters; ix++, texturePointer_f++) if(fabs((double) *texturePointer_f) < 1e-9) { *texturePointer_f = 0.0; }
}
// End of HDR conversion code...
}
else {
// Standard LDR texture 8 bpc conversion routines -- Fast path.
// Improved implementation: Takes 13 ms on a 800x800 texture...
if(isImageMatrixDoubles && numMatrixPlanes==1){
texturePointer_b=(GLubyte*) texturePointer;
iters=xSize*ySize;
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= (GLubyte) *(doubleMatrix++);
}
textureRecord->depth=8;
}
// Improved version: Takes 3 ms on a 800x800 texture...
// NB: Implementing memcpy manually by a for-loop takes 10 ms! This is a huge difference.
// -> That's because memcpy on MacOS-X is implemented with hand-coded, highly tuned Assembler code for PowerPC.
// -> It's always wise to use system-routines if available, instead of coding it by yourself!
if(isImageMatrixBytes && numMatrixPlanes==1){
memcpy((void*) texturePointer, (void*) byteMatrix, xSize*ySize);
textureRecord->depth=8;
}
// New version: Takes 33 ms on a 800x800 texture...
if(isImageMatrixDoubles && numMatrixPlanes==2){
texturePointer_b=(GLubyte*) texturePointer;
iters=xSize*ySize;
rp=(double*) ((psych_uint64) doubleMatrix);
ap=(double*) ((psych_uint64) doubleMatrix + (psych_uint64) iters*sizeof(double));
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= (GLubyte) *(rp++);
*(texturePointer_b++)= (GLubyte) *(ap++);
}
textureRecord->depth=16;
}
// New version: Takes 20 ms on a 800x800 texture...
if(isImageMatrixBytes && numMatrixPlanes==2){
texturePointer_b=(GLubyte*) texturePointer;
iters=xSize*ySize;
rpb=(GLubyte*) ((psych_uint64) byteMatrix);
apb=(GLubyte*) ((psych_uint64) byteMatrix + (psych_uint64) iters);
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= *(rpb++);
*(texturePointer_b++)= *(apb++);
}
textureRecord->depth=16;
}
// Improved version: Takes 43 ms on a 800x800 texture...
if(isImageMatrixDoubles && numMatrixPlanes==3){
texturePointer_b=(GLubyte*) texturePointer;
iters=xSize*ySize;
rp=(double*) ((psych_uint64) doubleMatrix);
gp=(double*) ((psych_uint64) doubleMatrix + (psych_uint64) iters*sizeof(double));
bp=(double*) ((psych_uint64) gp + (psych_uint64) iters*sizeof(double));
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= (GLubyte) *(rp++);
*(texturePointer_b++)= (GLubyte) *(gp++);
*(texturePointer_b++)= (GLubyte) *(bp++);
}
textureRecord->depth=24;
}
// Improved version: Takes 25 ms on a 800x800 texture...
if(isImageMatrixBytes && numMatrixPlanes==3){
texturePointer_b=(GLubyte*) texturePointer;
iters=xSize*ySize;
rpb=(GLubyte*) ((psych_uint64) byteMatrix);
gpb=(GLubyte*) ((psych_uint64) byteMatrix + (psych_uint64) iters);
bpb=(GLubyte*) ((psych_uint64) gpb + (psych_uint64) iters);
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= *(rpb++);
*(texturePointer_b++)= *(gpb++);
*(texturePointer_b++)= *(bpb++);
}
textureRecord->depth=24;
}
// Improved version: Takes 55 ms on a 800x800 texture...
if(isImageMatrixDoubles && numMatrixPlanes==4){
texturePointer_b=(GLubyte*) texturePointer;
iters=xSize*ySize;
rp=(double*) ((psych_uint64) doubleMatrix);
gp=(double*) ((psych_uint64) doubleMatrix + (psych_uint64) iters*sizeof(double));
bp=(double*) ((psych_uint64) gp + (psych_uint64) iters*sizeof(double));
ap=(double*) ((psych_uint64) bp + (psych_uint64) iters*sizeof(double));
if (bigendian) {
// Code for big-endian machines like PowerPC:
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= (GLubyte) *(ap++);
*(texturePointer_b++)= (GLubyte) *(rp++);
*(texturePointer_b++)= (GLubyte) *(gp++);
*(texturePointer_b++)= (GLubyte) *(bp++);
}
}
else {
// Code for little-endian machines like Intel Pentium:
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= (GLubyte) *(bp++);
*(texturePointer_b++)= (GLubyte) *(gp++);
*(texturePointer_b++)= (GLubyte) *(rp++);
*(texturePointer_b++)= (GLubyte) *(ap++);
}
}
textureRecord->depth=32;
}
// Improved version: Takes 33 ms on a 800x800 texture...
if(isImageMatrixBytes && numMatrixPlanes==4){
texturePointer_b=(GLubyte*) texturePointer;
iters=xSize*ySize;
rpb=(GLubyte*) ((psych_uint64) byteMatrix);
gpb=(GLubyte*) ((psych_uint64) byteMatrix + (psych_uint64) iters);
bpb=(GLubyte*) ((psych_uint64) gpb + (psych_uint64) iters);
apb=(GLubyte*) ((psych_uint64) bpb + (psych_uint64) iters);
if (bigendian) {
// Code for big-endian machines like PowerPC:
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= *(apb++);
*(texturePointer_b++)= *(rpb++);
*(texturePointer_b++)= *(gpb++);
*(texturePointer_b++)= *(bpb++);
}
}
else {
// Code for little-endian machines like Intel Pentium:
for(ix=0;ix<iters;ix++){
*(texturePointer_b++)= *(bpb++);
*(texturePointer_b++)= *(gpb++);
*(texturePointer_b++)= *(rpb++);
*(texturePointer_b++)= *(apb++);
}
}
textureRecord->depth=32;
}
} // End of 8 bpc texture conversion code (fast-path for LDR textures)
// The memory buffer now contains our texture data in a format ready to submit to OpenGL.
// Assign parent window and copy its inheritable properties:
PsychAssignParentWindow(textureRecord, windowRecord);
// Texture orientation is zero aka transposed aka non-renderswapped.
textureRecord->textureOrientation = ((assume_texorientation != 2) && (assume_texorientation != 3)) ? 0 : 2;
// This is our best guess about the number of image channels:
textureRecord->nrchannels = numMatrixPlanes;
// Let's create and bind a new texture object and fill it with our new texture data.
PsychCreateTexture(textureRecord);
// Assign GLSL filter-/lookup-shaders if needed:
PsychAssignHighPrecisionTextureShaders(textureRecord, windowRecord, usefloatformat, (usepoweroftwo & 2) ? 1 : 0);
// User specified override shader for this texture provided? This is useful for
// basic image processing and procedural texture shading:
if (textureShader!=0) {
// Assign provided shader as filtershader to this texture: We negate it so
// that the texture blitter routines know this is a custom shader, not our
// built in filter shader:
textureRecord->textureFilterShader = -1 * textureShader;
}
// Texture ready. Mark it valid and return handle to userspace:
PsychSetWindowRecordValid(textureRecord);
PsychCopyOutDoubleArg(1, FALSE, textureRecord->windowIndex);
// Swapping the texture to upright orientation requested?
if (assume_texorientation == 1) {
// Transform sourceRecord source texture into a normalized, upright texture if it isn't already in
// that format. We require this standard orientation for simplified shader design.
PsychSetShader(windowRecord, 0);
PsychNormalizeTextureOrientation(textureRecord);
}
// Shall the texture be finally declared "normally oriented"?
// This is either due to explicit renderswapping if assume_textureorientation == 1,
// or because it was already pretransposed in Matlab/Octave if assume_textureorientation == 2,
// or because user space tells us the texture is isotropic if assume_textureorientation == 3.
if (assume_texorientation > 0) {
// Yes. Label it as such:
textureRecord->textureOrientation = 2;
}
if(PsychPrefStateGet_DebugMakeTexture()) //MARK #4
StoreNowTime();
return(PsychError_none);
}
PsychError SCREENGetCapturedImage(void)
{
PsychWindowRecordType *windowRecord;
PsychWindowRecordType *textureRecord;
PsychRectType rect;
double summed_intensity;
int capturehandle = -1;
int waitForImage = TRUE;
int specialmode = 0;
double timeout, tnow;
double presentation_timestamp = 0;
int rc=-1;
double targetmemptr = 0;
double* tsummed = NULL;
psych_uint8 *targetmatrixptr = NULL;
static rawcapimgdata rawCaptureBuffer = {0, 0, 0, NULL};
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(6)); // Max. 6 input args.
PsychErrorExit(PsychRequireNumInputArgs(2)); // Min. 2 input args required.
PsychErrorExit(PsychCapNumOutputArgs(4)); // Max. 4 output args.
// Get the window record from the window record argument and get info from the window record
PsychAllocInWindowRecordArg(kPsychUseDefaultArgPosition, TRUE, &windowRecord);
// Only onscreen windows allowed:
if(!PsychIsOnscreenWindow(windowRecord) && !PsychIsOffscreenWindow(windowRecord)) {
PsychErrorExitMsg(PsychError_user, "GetCapturedImage called on something else than an onscreen window or offscreen window.");
}
// Get the handle:
PsychCopyInIntegerArg(2, TRUE, &capturehandle);
if (capturehandle==-1) {
PsychErrorExitMsg(PsychError_user, "GetCapturedImage called without valid handle to a capture object.");
}
// Get the 'waitForImage' flag: If waitForImage == true == 1, we'll do a blocking wait for
// arrival of a new image. Otherwise we will return with a 0-Handle if there
// isn't any new image available.
PsychCopyInIntegerArg(3, FALSE, &waitForImage);
// Special case waitForImage == 4? This would ask to call into the capture driver, but
// not wait for any image to arrive and not return any information. This is only useful
// on OS/X and Windows when using the capture engine for video recording to harddisk. In
// that case we are not interested at all in the captured live video, we just want it to
// get written to harddisk in the background. To keep the video encoder going, we need to
// call its SGIdle() routine and waitForImage==4 does just that, call SGIdle().
if (waitForImage == 4) {
// Perform the null-call to the capture engine, ie a SGIdle() on OS/X and Windows:
PsychGetTextureFromCapture(windowRecord, capturehandle, 4, 0.0, NULL, NULL, NULL, NULL);
// Done. Nothing to return...
return(PsychError_none);
}
// Get the optional textureRecord for the optional texture handle. If the calling script
// provides the texture handle of an existing Psychtoolbox texture that has a matching
// format, then that texture is recycled by overwriting its previous content with the
// image data from the new captured image. This can save some overhead for texture destruction
// and recreation. While this is probably not noticeable on mid- to high-end gfx cards with
// rectangle texture support, it can provide a significant speedup on low-end gfx cards with
// only power-of-two texture support.
textureRecord = NULL;
if ((PsychGetNumInputArgs()>=4) && PsychIsWindowIndexArg(4)) PsychAllocInWindowRecordArg(4, FALSE, &textureRecord);
// Get the optional specialmode flag:
PsychCopyInIntegerArg(5, FALSE, &specialmode);
// Set a 10 second maximum timeout for waiting for new frames:
PsychGetAdjustedPrecisionTimerSeconds(&timeout);
timeout+=10;
while (rc==-1) {
// We pass a checkForImage value of 2 if waitForImage>0. This way we can signal if we are in polling or blocking mode.
// With the libdc1394 engine this allows to do a real blocking wait in the driver -- much more efficient than the spin-waiting approach!
rc = PsychGetTextureFromCapture(windowRecord, capturehandle, ((waitForImage>0 && waitForImage<3) ? 2 : 1), 0.0, NULL, &presentation_timestamp, NULL, &rawCaptureBuffer);
PsychGetAdjustedPrecisionTimerSeconds(&tnow);
if (rc==-2 || (tnow > timeout)) {
// No image available and there won't be any in the future, because capture has been stopped or there is a timeout:
if (tnow > timeout) printf("PTB-WARNING: In Screen('GetCapturedImage') timed out waiting for a new frame. No video data in over 10 seconds!\n");
// No new texture available: Return a negative handle:
PsychCopyOutDoubleArg(1, TRUE, -1);
// ...and an invalid timestamp:
PsychCopyOutDoubleArg(2, FALSE, -1);
PsychCopyOutDoubleArg(3, FALSE, 0);
PsychCopyOutDoubleArg(4, FALSE, 0);
// Ready!
return(PsychError_none);
}
else if (rc==-1 && (waitForImage == 0 || waitForImage == 3)) {
// We should just poll once and no new texture available: Return a null-handle:
PsychCopyOutDoubleArg(1, TRUE, 0);
// ...and the current timestamp:
PsychCopyOutDoubleArg(2, FALSE, presentation_timestamp);
PsychCopyOutDoubleArg(3, FALSE, 0);
PsychCopyOutDoubleArg(4, FALSE, 0);
// Ready!
return(PsychError_none);
}
else if (rc==-1 && waitForImage != 0) {
// No new texture available yet. Just sleep a bit and then retry...
PsychYieldIntervalSeconds(0.002);
}
}
// rc == 0 --> New image available: Go ahead...
if (waitForImage!=2 && waitForImage!=3) {
// Ok, we need a texture for the image. Did script provide an old one for recycling?
if (textureRecord) {
// Old texture provided for reuse? Some basic sanity check: Everything else is
// up to the lower level PsychGetTextureFromCapture() routine.
if(!PsychIsOffscreenWindow(textureRecord)) {
PsychErrorExitMsg(PsychError_user, "GetCapturedImage provided with something else than a texture as fourth call parameter.");
}
}
else {
// No old texture provided: Create a new texture record:
PsychCreateWindowRecord(&textureRecord);
// Set mode to 'Texture':
textureRecord->windowType=kPsychTexture;
// We need to assign the screen number of the onscreen-window.
textureRecord->screenNumber=windowRecord->screenNumber;
// It defaults to a 32 bit texture for captured images. On Linux, this will be overriden,
// if optimized formats exist for our purpose:
textureRecord->depth=32;
textureRecord->nrchannels = 4;
// Create default rectangle which describes the dimensions of the image. Will be overwritten
// later on.
PsychMakeRect(rect, 0, 0, 10, 10);
PsychCopyRect(textureRecord->rect, rect);
// Other setup stuff:
textureRecord->textureMemorySizeBytes= 0;
textureRecord->textureMemory=NULL;
// Assign parent window and copy its inheritable properties:
PsychAssignParentWindow(textureRecord, windowRecord);
// Set textureNumber to zero, which means "Not cached, do not recycle"
// Todo: Texture recycling like in PsychMovieSupport for higher efficiency!
textureRecord->textureNumber = 0;
}
// Power-of-two texture requested?
if (specialmode & 0x01) {
// Yes. Spec it:
textureRecord->texturetarget = GL_TEXTURE_2D;
}
}
else {
// Just want to return summed_intensity and timestamp, not real texture...
textureRecord = NULL;
}
// Default to no calculation of summed image intensity:
tsummed = NULL;
if ((PsychGetNumOutputArgs() > 3) && !(specialmode & 0x2)) {
// Return sum of pixel intensities for all channels of this image: Need to
// assign the output pointer for this to happen:
tsummed = &summed_intensity;
}
// Try to fetch an image from the capture object and return it as texture:
targetmatrixptr = NULL;
// Shall we return a Matlab matrix?
if ((PsychGetNumOutputArgs() > 3) && (specialmode & 0x2)) {
// We shall return a matrix with raw image data. Allocate a uint8 matrix
// of sufficient size:
PsychAllocOutUnsignedByteMatArg(4, TRUE, rawCaptureBuffer.depth, rawCaptureBuffer.w, rawCaptureBuffer.h, &targetmatrixptr);
tsummed = NULL;
}
// Shall we return data into preallocated memory buffer?
if (specialmode & 0x4) {
// Copy in memory address (which itself is encoded in a double value):
PsychCopyInDoubleArg(6, TRUE, &targetmemptr);
targetmatrixptr = (psych_uint8*) PsychDoubleToPtr(targetmemptr);
}
if (targetmatrixptr == NULL) {
// Standard fetch of a texture and its timestamp:
rc = PsychGetTextureFromCapture(windowRecord, capturehandle, 0, 0.0, textureRecord, &presentation_timestamp, tsummed, NULL);
}
else {
// Fetch of a memory raw image buffer + timestamp + possibly a texture:
rawCaptureBuffer.data = (void*) targetmatrixptr;
rc = PsychGetTextureFromCapture(windowRecord, capturehandle, 0, 0.0, textureRecord, &presentation_timestamp, tsummed, &rawCaptureBuffer);
}
if (tsummed) {
// Return sum of pixel intensities for all channels of this image:
PsychCopyOutDoubleArg(4, FALSE, summed_intensity);
}
// Real texture requested?
if (textureRecord) {
// Texture ready for consumption.
// Assign GLSL filter-/lookup-shaders if needed: usefloatformat is always == 0 as
// our current capture engine implementations only return 8 bpc fixed textures.
// The 'userRequest' flag is set if specialmode flag is set to 8.
PsychAssignHighPrecisionTextureShaders(textureRecord, windowRecord, 0, (specialmode & 8) ? 1 : 0);
// specialmode setting 16? Disable auto-mipmap generation:
if (specialmode & 16) textureRecord->specialflags |= kPsychDontAutoGenMipMaps;
// Mark it valid and return handle to userspace:
PsychSetWindowRecordValid(textureRecord);
PsychCopyOutDoubleArg(1, TRUE, textureRecord->windowIndex);
}
else {
PsychCopyOutDoubleArg(1, TRUE, 0);
}
// Return presentation timestamp for this image:
PsychCopyOutDoubleArg(2, FALSE, presentation_timestamp);
// Return count of pending frames in buffers or of dropped frames:
PsychCopyOutDoubleArg(3, FALSE, (double) rc);
// Ready!
return(PsychError_none);
}
PsychError SCREENOpenOffscreenWindow(void)
{
int screenNumber, depth, targetScreenNumber;
PsychRectType rect;
PsychColorType color;
PsychWindowRecordType *exampleWindowRecord, *windowRecord, *targetWindow;
psych_bool wasColorSupplied;
char* texturePointer;
size_t xSize, ySize, nbytes;
psych_bool bigendian;
GLubyte *rpb;
int ix;
GLenum fboInternalFormat;
psych_bool needzbuffer;
psych_bool overridedepth = FALSE;
int usefloatformat = 0;
int specialFlags = 0;
int multiSample = 0;
// Detect endianity (byte-order) of machine:
ix=255;
rpb=(GLubyte*) &ix;
bigendian = ( *rpb == 255 ) ? FALSE : TRUE;
ix = 0; rpb = NULL;
//all sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
//cap the number of inputs
PsychErrorExit(PsychCapNumInputArgs(6)); //The maximum number of inputs
PsychErrorExit(PsychCapNumOutputArgs(2)); //The maximum number of outputs
//1-User supplies a window ptr 2-User supplies a screen number 3-User supplies rect and pixel size
if(PsychIsWindowIndexArg(1)){
PsychAllocInWindowRecordArg(1, TRUE, &exampleWindowRecord);
// Assign normalized copy of example windows rect -- Top-Left corner is always (0,0)
PsychNormalizeRect(exampleWindowRecord->clientrect, rect);
// We copy depth only from exampleWindow if it is a offscreen window (=texture). Copying from
// onscreen windows doesn't make sense, e.g. depth=16 for onscreen means RGBA8 window, but it
// would map onto a LUMINANCE+ALPHA texture for the offscreen window! We always use 32 bit RGBA8
// in such a case.
depth=(PsychIsOffscreenWindow(exampleWindowRecord)) ? exampleWindowRecord->depth : 32;
// unless it is a FBO backed onscreen window in imaging mode: Then we can use the depth from it.
if (exampleWindowRecord->imagingMode & kPsychNeedFastBackingStore || exampleWindowRecord->imagingMode & kPsychNeedFastOffscreenWindows) depth = exampleWindowRecord->depth;
targetScreenNumber=exampleWindowRecord->screenNumber;
targetWindow=exampleWindowRecord;
} else if(PsychIsScreenNumberArg(1)){
PsychCopyInScreenNumberArg(1, TRUE, &screenNumber);
PsychGetScreenRect(screenNumber, rect);
depth=32; // Always use RGBA8 in this case! See above...
targetScreenNumber=screenNumber;
targetWindow=NULL;
} else if(PsychIsUnaffiliatedScreenNumberArg(1)){ //that means -1 or maybe also NaN if we add that option.
// Default to a depth of 32 bpp:
depth = 32;
targetWindow = NULL;
// Get first open onscreen window as target window:
PsychFindScreenWindowFromScreenNumber(kPsychUnaffiliatedWindow, &targetWindow);
if (targetWindow == NULL) PsychErrorExitMsg(PsychError_user, "Could not find any open onscreen window to act as parent for this offscreen window. Open an onscreen window first!");
targetScreenNumber = targetWindow->screenNumber;
PsychGetScreenRect(targetScreenNumber, rect);
} else {
targetScreenNumber = 0; // Make compiler happy.
PsychErrorExit(PsychError_invalidNumdex);
}
if (targetWindow==NULL) {
// Get target window of screen:
PsychFindScreenWindowFromScreenNumber(targetScreenNumber, &targetWindow);
if (targetWindow == NULL) PsychErrorExitMsg(PsychError_user, "Could not find any open onscreen window to act as parent for this offscreen window. Open an onscreen window first!");
targetScreenNumber = targetWindow->screenNumber;
}
//Depth and rect argument supplied as arguments override those inherited from reference screen or window.
//Note that PsychCopyIn* prefix means that value will not be overwritten if the arguments are not present.
PsychCopyInRectArg(3,FALSE, rect);
if (IsPsychRectEmpty(rect)) PsychErrorExitMsg(PsychError_user, "Invalid rect value provided: Empty rects are not allowed.");
// Copy in optional depth: This gets overriden in many ways if imaging pipeline is on:
if (PsychCopyInIntegerArg(4,FALSE, &depth)) overridedepth = TRUE;
// If any of the no longer supported values 0, 1, 2 or 4 is provided, we
// silently switch to 32 bits per pixel, which is the safest and fastest setting:
if (depth==0 || depth==1 || depth==2 || depth==4) depth=32;
// Final sanity check:
if (!(targetWindow->imagingMode & kPsychNeedFastOffscreenWindows) && !(targetWindow->imagingMode & kPsychNeedFastBackingStore) && (depth==64 || depth==128)) {
PsychErrorExitMsg(PsychError_user, "Invalid depth value provided. Must be 8 bpp, 16 bpp, 24 bpp or 32 bpp, unless you enable the imaging pipeline, which provides you with more options!");
}
if (depth!=8 && depth!=16 && depth!=24 && depth!=32 && depth!=64 && depth!=128) {
PsychErrorExitMsg(PsychError_user, "Invalid depth value provided. Must be 8 bpp, 16 bpp, 24 bpp, 32 bpp, or if imagingmode is enabled also 64 bpp or 128 bpp!");
}
// If the imaging pipeline is enabled for the associated onscreen window and fast backing store, aka FBO's
// is requested, then we only accept depths of at least 32 bit, i.e. RGBA windows. We override any lower
// precision spec. This is because some common hardware only supports rendering to RGBA textures, not to
// RGB, LA or Luminance textures.
if ((targetWindow->imagingMode & kPsychNeedFastBackingStore || targetWindow->imagingMode & kPsychNeedFastOffscreenWindows) && (depth < 32)) depth = 32;
// Find the color for the window background.
wasColorSupplied=PsychCopyInColorArg(kPsychUseDefaultArgPosition, FALSE, &color);
// If none provided, use a proper white-value for this window:
if(!wasColorSupplied) PsychLoadColorStruct(&color, kPsychIndexColor, PsychGetWhiteValueFromWindow(targetWindow));
// Get the optional specialmode flag:
PsychCopyInIntegerArg(5, FALSE, &specialFlags);
// OpenGL-ES only supports GL_TEXTURE_2D targets, so enforce these via flags setting 1:
if (PsychIsGLES(targetWindow)) specialFlags |= 1;
// This command converts whatever color we got into RGBA format:
PsychCoerceColorMode(&color);
// printf("R=%i G=%i B=%i A=%i I=%i", color.value.rgba.r, color.value.rgba.g,color.value.rgba.b,color.value.rgba.a,color.value.index);
// First allocate the offscreen window record to store stuff into. If we exit with an error PsychErrorExit() should
// call PsychPurgeInvalidWindows which will clean up the window record.
PsychCreateWindowRecord(&windowRecord); // This also fills the window index field.
// This offscreen window is implemented as a Psychtoolbox texture:
windowRecord->windowType=kPsychTexture;
// We need to assign the screen number of the onscreen-window, so PsychCreateTexture()
// can query the size of the screen/onscreen-window...
windowRecord->screenNumber = targetScreenNumber;
// Assign the computed depth:
windowRecord->depth=depth;
// Default number of channels:
windowRecord->nrchannels=depth / 8;
// Assign the computed rect, but normalize it to start with top-left at (0,0):
PsychNormalizeRect(rect, windowRecord->rect);
// Client rect of an offscreen window is always == rect of it:
PsychCopyRect(windowRecord->clientrect, windowRecord->rect);
// Until here no OpenGL commands executed. Now we need a valid context: Set targetWindow
// as drawing target. This will perform neccessary context-switch and all backbuffer
// backup/restore/whatever operations to make sure we can do what we want without
// possibly screwing any offscreen windows and bindings:
if (PsychIsOnscreenWindow(targetWindow) || PsychIsOffscreenWindow(targetWindow)) {
// This is a possible on-/offscreen drawingtarget:
PsychSetDrawingTarget(targetWindow);
}
else {
// This must be a proxy-window object: Can't transition to it!
// But we can safe-reset the current drawingtarget...
PsychSetDrawingTarget((PsychWindowRecordType*) 0x1);
// ...and then switch to the OpenGL context of the 'targetWindow' proxy object:
PsychSetGLContext(targetWindow);
// Ok, framebuffer and bindings are safe and disabled, context is set. We
// should be safe to continue with the proxy...
}
// From here on we have a defined context and state. We can detach the drawing target whenever
// we want, as everything is backed up somewhere for later reinit.
// Create offscreen window either new style as FBO, or old style as texture:
if ((targetWindow->imagingMode & kPsychNeedFastBackingStore) || (targetWindow->imagingMode & kPsychNeedFastOffscreenWindows)) {
// Imaging mode for this window enabled: Use new way of creating the offscreen window:
// We safely unbind any FBO bindings and drawingtargets:
PsychSetDrawingTarget((PsychWindowRecordType*) 0x1);
// Overriden for imagingmode: There we always have 4 channels...
windowRecord->nrchannels=4;
// Start off with standard 8 bpc fixed point:
fboInternalFormat = GL_RGBA8; windowRecord->depth=32; usefloatformat = 0;
// Need 16 bpc fixed point precision?
if (targetWindow->imagingMode & kPsychNeed16BPCFixed) {
fboInternalFormat = (targetWindow->gfxcaps & kPsychGfxCapSNTex16) ? GL_RGBA16_SNORM : GL_RGBA16;
windowRecord->depth=64;
usefloatformat = 0;
}
// Need 16 bpc floating point precision?
if (targetWindow->imagingMode & kPsychNeed16BPCFloat) { fboInternalFormat = GL_RGBA_FLOAT16_APPLE; windowRecord->depth=64; usefloatformat = 1; }
// Need 32 bpc floating point precision?
if (targetWindow->imagingMode & kPsychNeed32BPCFloat) { fboInternalFormat = GL_RGBA_FLOAT32_APPLE; windowRecord->depth=128; usefloatformat = 2; }
// Override depth value provided?
if (overridedepth) {
// Manual depth specified: Override with that depth:
switch(depth) {
case 32:
fboInternalFormat = GL_RGBA8; windowRecord->depth=32; usefloatformat = 0;
break;
case 64:
fboInternalFormat = GL_RGBA_FLOAT16_APPLE; windowRecord->depth=64; usefloatformat = 1;
// Need fallback for lack of float 16 support?
if (!(targetWindow->gfxcaps & kPsychGfxCapFPTex16) && !PsychIsGLES(targetWindow)) {
// Yes. Try 16 bit signed normalized texture instead:
if (PsychPrefStateGet_Verbosity() > 4)
printf("PTB-INFO:OpenOffscreenWindow: Code requested 16 bpc float precision, but this is unsupported. Trying to use 15 bit snorm precision instead.\n");
fboInternalFormat = GL_RGBA16_SNORM; windowRecord->depth=64; usefloatformat = 0;
if (!(targetWindow->gfxcaps & kPsychGfxCapSNTex16)) {
printf("PTB-ERROR:OpenOffscreenWindow: Code requested 16 bpc float precision, but this is unsupported by this graphics card.\n");
printf("PTB-ERROR:OpenOffscreenWindow: Tried to use 16 bit snorm format instead, but failed as this is unsupported as well.\n");
}
}
break;
case 128:
fboInternalFormat = GL_RGBA_FLOAT32_APPLE; windowRecord->depth=128; usefloatformat = 2;
break;
default:
fboInternalFormat = GL_RGBA8; windowRecord->depth=32; usefloatformat = 0;
}
}
// Floating point framebuffer on OpenGL-ES requested?
if (PsychIsGLES(targetWindow) && (usefloatformat > 0)) {
// Yes. We only support 32 bpc float framebuffers with alpha-blending. On less supportive hardware we fail:
if (!(targetWindow->gfxcaps & kPsychGfxCapFPTex32) || !(targetWindow->gfxcaps & kPsychGfxCapFPFBO32)) {
PsychErrorExitMsg(PsychError_user, "Sorry, the requested offscreen window color resolution of 32 bpc floating point is not supported by your graphics card. Game over.");
}
// Supported. Upgrade requested format to 32 bpc float, whatever it was before:
fboInternalFormat = GL_RGBA_FLOAT32_APPLE; windowRecord->depth=128; usefloatformat = 2;
}
// Do we need additional depth buffer attachments?
needzbuffer = (PsychPrefStateGet_3DGfx()>0) ? TRUE : FALSE;
// Copy in optional multiSample argument: It defaults to zero, aka multisampling disabled.
PsychCopyInIntegerArg(6, FALSE, &multiSample);
if (multiSample < 0) PsychErrorExitMsg(PsychError_user, "Invalid negative multiSample level provided!");
// Multisampled anti-aliasing requested?
if (multiSample > 0) {
// Yep. Supported by GPU?
if (!(targetWindow->gfxcaps & kPsychGfxCapFBOMultisample)) {
// No. We fall back to non-multisampled mode:
multiSample = 0;
// Tell user if warnings enabled:
if (PsychPrefStateGet_Verbosity() > 1) {
printf("PTB-WARNING: You requested stimulus anti-aliasing via multisampling by setting the multiSample parameter of Screen('OpenOffscreenWindow', ...) to a non-zero value.\n");
printf("PTB-WARNING: You also requested use of the imaging pipeline. Unfortunately, your combination of operating system, graphics hardware and driver does not\n");
printf("PTB-WARNING: support simultaneous use of the imaging pipeline and multisampled anti-aliasing.\n");
printf("PTB-WARNING: Will therefore continue without anti-aliasing...\n\n");
printf("PTB-WARNING: A driver upgrade may resolve this issue. Users of MacOS-X need at least OS/X 10.5.2 Leopard for support on recent ATI hardware.\n\n");
}
}
}
// Allocate framebuffer object for this Offscreen window:
if (!PsychCreateFBO(&(windowRecord->fboTable[0]), fboInternalFormat, needzbuffer, (int) PsychGetWidthFromRect(rect), (int) PsychGetHeightFromRect(rect), multiSample, specialFlags)) {
// Failed!
PsychErrorExitMsg(PsychError_user, "Creation of Offscreen window in imagingmode failed for some reason :(");
}
// Assign this FBO as drawBuffer for mono channel of our Offscreen window:
windowRecord->drawBufferFBO[0] = 0;
windowRecord->fboCount = 1;
// Assign it as texture as well:
windowRecord->textureNumber = windowRecord->fboTable[0]->coltexid;
windowRecord->textureMemorySizeBytes = 0;
windowRecord->textureMemory = NULL;
windowRecord->texturetarget = (specialFlags & 0x1) ? GL_TEXTURE_2D : GL_TEXTURE_RECTANGLE_EXT;
windowRecord->surfaceSizeBytes = (size_t) (PsychGetWidthFromRect(rect) * PsychGetHeightFromRect(rect) * (windowRecord->depth / 8));
// Set bpc for FBO backed offscreen window:
windowRecord->bpc = (int) (windowRecord->depth / 4);
// Initial setup done, continues below after some shared code...
}
else {
// Traditional texture creation code:
// Special case for alpha-channel: DBL_MAX signals maximum alpha
// value requested. In our own code we need to manually map this to
// the maximum uint8 alpha value of 255:
if (color.value.rgba.a == DBL_MAX) color.value.rgba.a = 255;
// Allocate the texture memory:
// We only allocate the amount really needed for given format, aka numMatrixPlanes - Bytes per pixel.
xSize = (size_t) PsychGetWidthFromRect(rect);
ySize = (size_t) PsychGetHeightFromRect(rect);
windowRecord->textureMemorySizeBytes = ((size_t) (depth/8)) * xSize * ySize;
windowRecord->textureMemory = malloc(windowRecord->textureMemorySizeBytes);
texturePointer=(char*) windowRecord->textureMemory;
// printf("depth=%i xsize=%i ysize=%i mem=%i ptr=%p", depth, xSize, ySize, windowRecord->textureMemorySizeBytes, texturePointer);
// Fill with requested background color:
nbytes=0;
switch (depth) {
case 8: // Pure LUMINANCE texture:
memset((void*) texturePointer, (int) color.value.rgba.r, windowRecord->textureMemorySizeBytes);
break;
case 16: // LUMINANCE + ALPHA
while (nbytes < windowRecord->textureMemorySizeBytes) {
*(texturePointer++) = (psych_uint8) color.value.rgba.r;
*(texturePointer++) = (psych_uint8) color.value.rgba.a;
nbytes+=2;
}
break;
case 24: // RGB:
while (nbytes < windowRecord->textureMemorySizeBytes) {
*(texturePointer++) = (psych_uint8) color.value.rgba.r;
*(texturePointer++) = (psych_uint8) color.value.rgba.g;
*(texturePointer++) = (psych_uint8) color.value.rgba.b;
nbytes+=3;
}
break;
case 32: // RGBA
if (bigendian) {
// Code for big-endian machines, e.g., PowerPC:
while (nbytes < windowRecord->textureMemorySizeBytes) {
*(texturePointer++) = (psych_uint8) color.value.rgba.a;
*(texturePointer++) = (psych_uint8) color.value.rgba.r;
*(texturePointer++) = (psych_uint8) color.value.rgba.g;
*(texturePointer++) = (psych_uint8) color.value.rgba.b;
nbytes+=4;
}
}
else {
// Code for little-endian machines, e.g., IntelPC, IntelMAC, aka Pentium.
while (nbytes < windowRecord->textureMemorySizeBytes) {
*(texturePointer++) = (psych_uint8) color.value.rgba.b;
*(texturePointer++) = (psych_uint8) color.value.rgba.g;
*(texturePointer++) = (psych_uint8) color.value.rgba.r;
*(texturePointer++) = (psych_uint8) color.value.rgba.a;
nbytes+=4;
}
}
break;
}
}
// Shared setup code for FBO vs. non-FBO Offscreen windows:
// Assign parent window and copy its inheritable properties:
PsychAssignParentWindow(windowRecord, targetWindow);
// Texture orientation is type 2 aka upright, non-transposed aka Offscreen window:
windowRecord->textureOrientation = 2;
if ((windowRecord->imagingMode & kPsychNeedFastBackingStore) || (windowRecord->imagingMode & kPsychNeedFastOffscreenWindows)) {
// Last step for FBO backed Offscreen window: Clear it to its background color:
PsychSetDrawingTarget(windowRecord);
// Set default draw shader:
PsychSetShader(windowRecord, -1);
// Set background fill color:
PsychSetGLColor(&color, windowRecord);
// Setup alpha-blending:
PsychUpdateAlphaBlendingFactorLazily(windowRecord);
// Fullscreen fill of a non-onscreen window:
PsychGLRect(windowRecord->rect);
// Multisampling requested? If so, we need to enable it:
if (multiSample > 0) {
glEnable(GL_MULTISAMPLE);
while (glGetError() != GL_NO_ERROR);
}
// Ready. Unbind it.
PsychSetDrawingTarget(NULL);
}
else {
// Old-style setup for non-FBO Offscreen windows:
// Special texture format?
if (specialFlags & 0x1) windowRecord->texturetarget = GL_TEXTURE_2D;
// Let's create and bind a new texture object and fill it with our new texture data.
PsychCreateTexture(windowRecord);
}
// Assign GLSL filter-/lookup-shaders if needed:
PsychAssignHighPrecisionTextureShaders(windowRecord, targetWindow, usefloatformat, (specialFlags & 2) ? 1 : 0);
// specialFlags setting 8? Disable auto-mipmap generation:
if (specialFlags & 0x8) windowRecord->specialflags |= kPsychDontAutoGenMipMaps;
// A specialFlags setting of 32? Protect texture against deletion via Screen('Close') without providing a explicit handle:
if (specialFlags & 32) windowRecord->specialflags |= kPsychDontDeleteOnClose;
// Window ready. Mark it valid and return handle to userspace:
PsychSetWindowRecordValid(windowRecord);
//Return the window index and the rect argument.
PsychCopyOutDoubleArg(1, FALSE, windowRecord->windowIndex);
PsychCopyOutRectArg(2, FALSE, rect);
// Ready.
return(PsychError_none);
}
PsychError SCREENSetOpenGLTexture(void)
{
PsychWindowRecordType *windowRecord, *textureRecord;
int texid, w, h, d, testarg, textureShader, usefloatformat = 0;
int specialFlags = 0;
GLenum target = 0;
texid=w=h=d=-1;
//all subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(9)); //The maximum number of inputs
PsychErrorExit(PsychRequireNumInputArgs(4)); //The required number of inputs
PsychErrorExit(PsychCapNumOutputArgs(2)); //The maximum number of outputs
// Get the window record from the window record argument and get info from the window record
PsychAllocInWindowRecordArg(kPsychUseDefaultArgPosition, TRUE, &windowRecord);
// Get the texture record from the texture record argument.
// Check if either none ( [] or '' ) or the special value zero was
// provided as Psychtoolbox textureHandle. In that case, we create a new
// empty texture record instead of reusing an existing one.
testarg=0;
PsychCopyInIntegerArg(2, FALSE, &testarg);
if (testarg==0) {
// No valid textureHandle provided. Create a new empty textureRecord.
PsychCreateWindowRecord(&textureRecord);
textureRecord->windowType=kPsychTexture;
textureRecord->screenNumber = windowRecord->screenNumber;
// Assign parent window and copy its inheritable properties:
PsychAssignParentWindow(textureRecord, windowRecord);
// Mark it valid and return handle to userspace:
PsychSetWindowRecordValid(textureRecord);
}
else {
// None of the special values provided. We assume its a handle to a valid
// and existing PTB texture and try to retrieve the textureRecord:
PsychAllocInWindowRecordArg(2, TRUE, &textureRecord);
}
// Is it a textureRecord?
if (!PsychIsTexture(textureRecord)) {
PsychErrorExitMsg(PsychError_user, "You tried to set texture information on something else than a texture!");
}
// Query OpenGL texid:
PsychCopyInIntegerArg(3, TRUE, &texid);
// Query OpenGL texture target:
PsychCopyInIntegerArg(4, TRUE, (int*) &target);
// Query optional override width:
PsychCopyInIntegerArg(5, FALSE, &w);
// Query optional override height:
PsychCopyInIntegerArg(6, FALSE, &h);
// Query optional override depth:
PsychCopyInIntegerArg(7, FALSE, &d);
// Get optional texture shader handle:
textureShader = 0;
PsychCopyInIntegerArg(8, FALSE, &textureShader);
// Get optional specialFlags:
PsychCopyInIntegerArg(9, FALSE, &specialFlags);
// Activate OpenGL rendering context of windowRecord:
PsychSetGLContext(windowRecord);
// Bind the provided external OpenGL texture object:
PsychTestForGLErrors();
glBindTexture(target, texid);
PsychTestForGLErrors();
// Binding worked. Query its size and format unless override values are given:
if (w==-1) glGetTexLevelParameteriv(target, 0, GL_TEXTURE_WIDTH, (GLint*) &w);
if (h==-1) glGetTexLevelParameteriv(target, 0, GL_TEXTURE_HEIGHT, (GLint*) &h);
if (d==-1) glGetTexLevelParameteriv(target, 0, GL_TEXTURE_DEPTH, (GLint*) &d);
if (w<=0) {
PsychErrorExitMsg(PsychError_user, "You tried to set invalid (negative) texture width.");
}
if (h<=0) {
PsychErrorExitMsg(PsychError_user, "You tried to set invalid (negative) texture height.");
}
if (d<=0) {
PsychErrorExitMsg(PsychError_user, "You tried to set invalid (negative) texture depth.");
}
// Ok, setup texture record for texture:
PsychInitWindowRecordTextureFields(textureRecord);
textureRecord->depth = d;
// Assume this texture has four channels. FIXME: Is this problematic?
textureRecord->nrchannels = 4;
PsychMakeRect(textureRecord->rect, 0, 0, w, h);
// Client rect of a texture is always == rect of it:
PsychCopyRect(textureRecord->clientrect, textureRecord->rect);
textureRecord->texturetarget = target;
// Orientation is set to 2 - like an upright Offscreen window texture:
textureRecord->textureOrientation = 2;
textureRecord->textureNumber = texid;
// Assign GLSL filter-/lookup-shaders if needed: usefloatformat is determined
// by query, whereas the 'userRequest' flag is set to zero for now.
glGetTexLevelParameteriv(target, 0, GL_TEXTURE_RED_SIZE, (GLint*) &d);
if (d <= 0) glGetTexLevelParameteriv(target, 0, GL_TEXTURE_LUMINANCE_SIZE, (GLint*) &d);
if (d < 16) usefloatformat = 0;
if (d >= 16) usefloatformat = 1;
if (d >= 32) usefloatformat = 2;
// Assign bpc value:
textureRecord->bpc = (int) d;
PsychAssignHighPrecisionTextureShaders(textureRecord, windowRecord, usefloatformat, (specialFlags & 2) ? 1 : 0);
// specialFlags setting 8? Disable auto-mipmap generation:
if (specialFlags & 0x8) textureRecord->specialflags |= kPsychDontAutoGenMipMaps;
// A specialFlags setting of 32? Protect texture against deletion via Screen('Close') without providing a explicit handle:
if (specialFlags & 32) textureRecord->specialflags |= kPsychDontDeleteOnClose;
// User specified override shader for this texture provided? This is useful for
// basic image processing and procedural texture shading:
if (textureShader!=0) {
// Assign provided shader as filtershader to this texture: We negate it so
// that the texture blitter routines know this is a custom shader, not our
// built in filter shader:
textureRecord->textureFilterShader = -1 * textureShader;
}
// Unbind texture:
glBindTexture(target, 0);
// printf("id %i target: %i w %i h %i", texid, target, w, h);
// Return new (or old) PTB textureHandle for this texture:
PsychCopyOutDoubleArg(1, FALSE, textureRecord->windowIndex);
PsychCopyOutRectArg(2, FALSE, textureRecord->rect);
// Done.
return(PsychError_none);
}
PsychError SCREENTransformTexture(void)
{
PsychWindowRecordType *sourceRecord, *targetRecord, *proxyRecord, *sourceRecord2;
int testarg, specialFlags, usefloatformat, d;
// All subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if (PsychIsGiveHelp()) { PsychGiveHelp(); return(PsychError_none); };
PsychErrorExit(PsychCapNumInputArgs(5));
PsychErrorExit(PsychRequireNumInputArgs(2));
PsychErrorExit(PsychCapNumOutputArgs(1));
// OpenGL FBO's supported? Otherwise this is a no-go...
if (glBindFramebufferEXT == NULL || glUseProgram == NULL) {
// Game over!
printf("PTB-ERROR: Sorry, your graphics driver & hardware does not support the required OpenGL framebuffer object extension or\n");
printf("PTB-ERROR: the OpenGL shading language for hardware accelerated fragment processing. This function is therefore disabled.\n");
printf("PTB-ERROR: You will need at least a NVidia GeforceFX-5200, a ATI Radeon 9600 or a Intel GMA-950 graphics card for this\n");
printf("PTB-ERROR: to work. If you have such a card (or a more recent one) then you'll need to update your graphics drivers.\n\n");
PsychErrorExitMsg(PsychError_user, "Screen('TransformTexture') command unsupported on your combination of graphics hardware & driver.");
}
// Get the window structure for the source texture.
PsychAllocInWindowRecordArg(1, TRUE, &sourceRecord);
if (!PsychIsTexture(sourceRecord))
PsychErrorExitMsg(PsychError_user, "'sourceTexture' argument must be a handle to a texture or offscreen window.");
// Get the window structure for the proxy object.
PsychAllocInWindowRecordArg(2, TRUE, &proxyRecord);
if (proxyRecord->windowType != kPsychProxyWindow)
PsychErrorExitMsg(PsychError_user, "'transformProxyPtr' argument must be a handle to a proxy object.");
// Test if optional specialFlags are provided:
specialFlags = 0;
PsychCopyInIntegerArg(5, FALSE, &specialFlags);
// Activate rendering context of the proxy object and soft-reset the drawing engine,
// so we're in a well defined state. The value 1 means: Reset safely, ie. do any
// framebuffer backups that might be needed before NULL-ing the binding:
PsychSetDrawingTarget((PsychWindowRecordType*) 0x1);
PsychSetGLContext(proxyRecord);
// Save all state:
glPushAttrib(GL_ALL_ATTRIB_BITS);
// Disable alpha-blending:
glDisable(GL_BLEND);
// Reset color write mask to "all enabled"
glColorMask(GL_TRUE,GL_TRUE,GL_TRUE,GL_TRUE);
// Disable any shaders:
PsychSetShader(proxyRecord, 0);
// Transform sourceRecord source texture into a normalized, upright texture if it isn't already in
// that format. We require this standard orientation for simplified shader design.
if (!(specialFlags & 1))
PsychNormalizeTextureOrientation(sourceRecord);
// Test if optional 2nd source texture is provided:
testarg = 0;
PsychCopyInIntegerArg(3, FALSE, &testarg);
if (testarg != 0) {
// Tes. Get the window structure for the 2nd source texture.
PsychAllocInWindowRecordArg(3, TRUE, &sourceRecord2);
if (!PsychIsTexture(sourceRecord2))
PsychErrorExitMsg(PsychError_user, "'sourceTexture2' argument must be a handle to a texture or offscreen window.");
// Transform sourceRecord2 source texture into a normalized, upright texture if it isn't already in
// that format. We require this standard orientation for simplified shader design.
if (!(specialFlags & 1))
PsychNormalizeTextureOrientation(sourceRecord2);
}
else {
// No secondary source texture:
sourceRecord2 = NULL;
}
// Restore proper rendering context:
PsychSetGLContext(proxyRecord);
// Test if optional target texture is provided:
testarg = 0;
PsychCopyInIntegerArg(4, FALSE, &testarg);
// Do we need to create a new one from scratch?
if (testarg == 0) {
// No valid textureHandle provided. Create a new empty textureRecord which clones some
// of the properties of the sourceRecord
targetRecord = NULL;
PsychCreateWindowRecord(&targetRecord);
PsychInitWindowRecordTextureFields(targetRecord);
targetRecord->windowType=kPsychTexture;
targetRecord->screenNumber = sourceRecord->screenNumber;
// Assign parent window and copy its inheritable properties:
PsychAssignParentWindow(targetRecord, sourceRecord);
targetRecord->depth = sourceRecord->depth;
// Assume this texture has four channels.
targetRecord->nrchannels = 4;
PsychCopyRect(targetRecord->rect, sourceRecord->rect);
PsychCopyRect(targetRecord->clientrect, targetRecord->rect);
targetRecord->texturetarget = sourceRecord->texturetarget;
// Orientation is set to 2 - like an upright Offscreen window texture:
targetRecord->textureOrientation = 2;
// Mark it valid and return handle to userspace:
PsychSetWindowRecordValid(targetRecord);
}
else {
// Get the window structure for the target texture.
PsychAllocInWindowRecordArg(4, TRUE, &targetRecord);
if (!PsychIsTexture(targetRecord))
PsychErrorExitMsg(PsychError_user, "'targetTexture' argument must be a handle to a texture or offscreen window.");
}
// Make sure our source textures have at least a pseudo FBO for read-access:
PsychCreateShadowFBOForTexture(sourceRecord, FALSE, -1);
if (sourceRecord2)
PsychCreateShadowFBOForTexture(sourceRecord2, FALSE, -1);
// Make sure the target texture is upright/normalized:
if (!(specialFlags & 1))
PsychNormalizeTextureOrientation(targetRecord);
// Make sure our target texture has a full-blown FBO attached as a rendertarget.
// As our proxy object defines the image processing ops, it also defines the
// required imagingMode properties for the target texture:
PsychCreateShadowFBOForTexture(targetRecord, TRUE, proxyRecord->imagingMode);
// Assign GLSL filter-/lookup-shaders if needed: usefloatformat is queried.
// The 'userRequest' flag is set depending on specialFlags setting & 2.
glBindTexture(targetRecord->texturetarget, targetRecord->textureNumber);
glGetTexLevelParameteriv(targetRecord->texturetarget, 0, GL_TEXTURE_RED_SIZE, (GLint*) &d);
if (d <= 0)
glGetTexLevelParameteriv(targetRecord->texturetarget, 0, GL_TEXTURE_LUMINANCE_SIZE, (GLint*) &d);
glBindTexture(targetRecord->texturetarget, 0);
usefloatformat = 0;
if (d == 16) usefloatformat = 1;
if (d >= 32) usefloatformat = 2;
PsychAssignHighPrecisionTextureShaders(targetRecord, sourceRecord, usefloatformat, (specialFlags & 2) ? 1 : 0);
// Make sure our proxy has suitable bounce buffers if we need any:
if (proxyRecord->imagingMode & (kPsychNeedDualPass | kPsychNeedMultiPass)) {
// Needs multi-pass processing. Create bounce buffer if neccessary:
PsychCopyRect(proxyRecord->rect, targetRecord->rect);
PsychCopyRect(proxyRecord->clientrect, targetRecord->rect);
// Build FBO for bounce-buffering. This will always be upright/normalized,
// so no need to normalize "texture orientation" for proxyRecord bounce buffers:
PsychCreateShadowFBOForTexture(proxyRecord, TRUE, proxyRecord->imagingMode);
}
// Make sure we don't have VRAM memory feedback loops:
if ((sourceRecord->textureNumber == targetRecord->textureNumber) ||
(sourceRecord2 && (sourceRecord2->textureNumber == targetRecord->textureNumber)))
PsychErrorExitMsg(PsychError_user, "Source texture and target texture must be different!");
// Apply image processing operation: Use ressources and OpenGL context of proxyRecord, run user defined blit chain,
// Don't supply user specific data (NULL), don't supply override blitter (NULL), source is read-only (TRUE), no
// swizzle allowed (FALSE), sourceRecord is source, targetRecord is destination, bounce buffers provided by proxyRecord,
// no secondary FBO available (NULL).
PsychPipelineExecuteHook(proxyRecord, kPsychUserDefinedBlit, NULL, NULL, TRUE, FALSE,
&(sourceRecord->fboTable[sourceRecord->drawBufferFBO[0]]), (sourceRecord2) ? &(sourceRecord2->fboTable[sourceRecord2->drawBufferFBO[0]]) : NULL,
&(targetRecord->fboTable[targetRecord->drawBufferFBO[0]]), (proxyRecord->drawBufferFBO[0]!=-1) ? &(proxyRecord->fboTable[proxyRecord->drawBufferFBO[0]]) : NULL);
// Restore previous settings:
glPopAttrib();
// Set "dirty" flag on texture: (Ab)used to trigger regeneration of mip-maps during texture drawing of mip-mapped textures.
targetRecord->needsViewportSetup = TRUE;
//Return the window index and the rect argument.
PsychCopyOutDoubleArg(1, FALSE, targetRecord->windowIndex);
// Done.
return(PsychError_none);
}
PsychError SCREENGetMovieImage(void)
{
PsychWindowRecordType *windowRecord;
PsychWindowRecordType *textureRecord;
PsychRectType rect;
double deadline, tnow;
int moviehandle = -1;
int waitForImage = TRUE;
double requestedTimeIndex = -1;
double presentation_timestamp = 0;
int rc=0;
int specialFlags = 0;
int specialFlags2 = 0;
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(6)); // Max. 6 input args.
PsychErrorExit(PsychRequireNumInputArgs(2)); // Min. 2 input args required.
PsychErrorExit(PsychCapNumOutputArgs(2)); // Max. 2 output args.
// Get the window record from the window record argument and get info from the window record
PsychAllocInWindowRecordArg(kPsychUseDefaultArgPosition, TRUE, &windowRecord);
// Only onscreen windows allowed:
if(!PsychIsOnscreenWindow(windowRecord)) {
PsychErrorExitMsg(PsychError_user, "GetMovieImage called on something else than an onscreen window.");
}
// Get the movie handle:
PsychCopyInIntegerArg(2, TRUE, &moviehandle);
if (moviehandle==-1) {
PsychErrorExitMsg(PsychError_user, "GetMovieImage called without valid handle to a movie object.");
}
// Get the 'waitForImage' flag: If waitForImage == true == 1, we'll do a blocking wait for
// arrival of a new image for playback. Otherwise we will return with a 0-Handle if there
// isn't any new image available.
PsychCopyInIntegerArg(3, FALSE, &waitForImage);
// Get the requested timeindex for the frame. The default is -1, which means: Get the next image,
// according to current movie playback time.
PsychCopyInDoubleArg(4, FALSE, &requestedTimeIndex);
// Get the optional specialFlags flag:
PsychCopyInIntegerArg(5, FALSE, &specialFlags);
// Get the optional specialFlags2 flag:
PsychCopyInIntegerArg(6, FALSE, &specialFlags2);
PsychGetAdjustedPrecisionTimerSeconds(&deadline);
deadline += 5;
while (rc==0) {
rc = PsychGetTextureFromMovie(windowRecord, moviehandle, TRUE, requestedTimeIndex, NULL, NULL);
PsychGetAdjustedPrecisionTimerSeconds(&tnow);
if (rc<0 || (tnow > deadline)) {
// No image available and there won't be any in the future, because the movie has reached
// its end and we are not in looped playback mode:
if (tnow > deadline) printf("PTB-ERROR: In Screen('GetMovieImage') for movie %i: Timed out while waiting for new frame after 5 seconds!\n", moviehandle);
// No new texture available: Return a negative handle:
PsychCopyOutDoubleArg(1, TRUE, -1);
// ...and an invalid timestamp:
PsychCopyOutDoubleArg(2, FALSE, -1);
// Ready!
return(PsychError_none);
}
else if (rc==0 && waitForImage == 0) {
// We should just poll once and no new texture available: Return a null-handle:
PsychCopyOutDoubleArg(1, TRUE, 0);
// ...and an invalid timestamp:
PsychCopyOutDoubleArg(2, FALSE, -1);
// Ready!
return(PsychError_none);
}
else if (rc==0 && waitForImage != 0) {
// No new texture available yet. Just sleep a bit and then retry...
PsychWaitIntervalSeconds(0.005);
}
}
// New image available: Go ahead...
// Create a texture record. Really just a window record adapted for textures.
PsychCreateWindowRecord(&textureRecord); // This also fills the window index field.
// Set mode to 'Texture':
textureRecord->windowType=kPsychTexture;
// We need to assign the screen number of the onscreen-window.
textureRecord->screenNumber=windowRecord->screenNumber;
// It is always a 32 bit texture for movie textures:
textureRecord->depth=32;
textureRecord->nrchannels = 4;
// Create default rectangle which describes the dimensions of the image. Will be overwritten
// later on.
PsychMakeRect(rect, 0, 0, 10, 10);
PsychCopyRect(textureRecord->rect, rect);
// Other setup stuff:
textureRecord->textureMemorySizeBytes= 0;
textureRecord->textureMemory=NULL;
// Assign parent window and copy its inheritable properties:
PsychAssignParentWindow(textureRecord, windowRecord);
// Try to fetch an image from the movie object and return it as texture:
PsychGetTextureFromMovie(windowRecord, moviehandle, FALSE, requestedTimeIndex, textureRecord, ((specialFlags2 & 1) ? NULL : &presentation_timestamp));
// Assign GLSL filter-/lookup-shaders if needed: usefloatformat is always == 0 as
// our current movie engine implementations only return 8 bpc fixed textures.
// The 'userRequest' flag is set if specialmode flag is set to 8.
PsychAssignHighPrecisionTextureShaders(textureRecord, windowRecord, 0, (specialFlags & 2) ? 1 : 0);
// Texture ready for consumption. Mark it valid and return handle to userspace:
PsychSetWindowRecordValid(textureRecord);
PsychCopyOutDoubleArg(1, TRUE, textureRecord->windowIndex);
// Return presentation timestamp for this image:
PsychCopyOutDoubleArg(2, FALSE, presentation_timestamp);
// Ready!
return(PsychError_none);
}
